<pre class="metadata">
Title: Web IDL
Shortname: WebIDL
Level: 2
Status: ED
Group: webplatform
Mailing list: public-script-coord@w3.org
Mailing List Archives: https://lists.w3.org/Archives/Public/public-script-coord/
Repository: heycam/webidl
!Feedback: <a href="https://github.com/heycam/webidl">GitHub</a> (<a href="https://github.com/heycam/webidl/issues/new">new issue</a>, <a href="https://github.com/heycam/webidl/issues">open issues</a>, <a href="https://www.w3.org/Bugs/Public/buglist.cgi?product=WebAppsWG&amp;component=WebIDL&amp;resolution=---">legacy bug tracker</a>)
ED: https://heycam.github.io/webidl/
Former Editor: Cameron McCormack, Mozilla Corporation, http://mcc.id.au/, cam@mcc.id.au
Editor: Boris Zbarsky, Mozilla Corporation, bzbarsky@mit.edu
Former Editor: Tobie Langel, https://tobie.me, tobie@unlockopen.com
Abstract: This document defines an interface definition language, Web IDL,
Abstract: that can be used to describe interfaces that are intended to be
Abstract: implemented in web browsers. Web IDL is an IDL variant with a
Abstract: number of features that allow the behavior of common script objects in
Abstract: the web platform to be specified more readily. How interfaces
Abstract: described with Web IDL correspond to constructs within ECMAScript
Abstract: execution environments is also detailed in this document.
Abstract: It is expected that this document acts
Abstract: as a guide to implementors of already-published specifications,
Abstract: and that newly published specifications reference this
Abstract: document to ensure conforming implementations of interfaces
Abstract: are interoperable.
Boilerplate: omit issues-index, omit conformance, omit feedback-header
Default Biblio Status: current
</pre>

<pre class="link-defaults">
spec: infra; type: dfn; text: list
spec: url; type: interface; text: URL
spec: dom; type: interface; text: Document
spec: ecma-262; type: dfn; for: /; text: internal method
spec: ecma-262; type: dfn; for: /; text: internal slot
spec: ecma-262; type: dfn; for: /; text:realm
</pre>

<pre class="anchors">
urlPrefix: https://www.khronos.org/registry/webgl/extensions/WEBGL_compressed_texture_astc/; spec: WEBGL_compressed_texture_astc
    type: interface; text: WEBGL_compressed_texture_astc
urlPrefix: https://www.khronos.org/registry/webgl/extensions/WEBGL_compressed_texture_s3tc_srgb/; spec: WEBGL_compressed_texture_s3tc_srgb
    type: interface; text: WEBGL_compressed_texture_s3tc_srgb
urlPrefix: https://www.khronos.org/registry/webgl/extensions/WEBGL_draw_buffers/; spec: WEBGL_draw_buffers
    type: interface; text: WEBGL_draw_buffers
urlPrefix: https://www.khronos.org/registry/webgl/extensions/WEBGL_lose_context/; spec: WEBGL_lose_context
    type: interface; text: WEBGL_lose_context
urlPrefix: https://www.khronos.org/registry/webgl/extensions/ANGLE_instanced_arrays/; spec: ANGLE_instanced_arrays
    type: interface; text: ANGLE_instanced_arrays
urlPrefix: https://www.khronos.org/registry/webgl/extensions/EXT_blend_minmax/; spec: EXT_blend_minmax
    type: interface; text: EXT_blend_minmax
urlPrefix: https://www.khronos.org/registry/webgl/extensions/EXT_color_buffer_float/; spec: EXT_color_buffer_float
    type: interface; text: EXT_color_buffer_float
urlPrefix: https://www.khronos.org/registry/webgl/extensions/EXT_disjoint_timer_query/; spec: EXT_disjoint_timer_query
    type: interface; text: EXT_disjoint_timer_query
urlPrefix: https://www.khronos.org/registry/webgl/extensions/OES_standard_derivatives/; spec: OES_standard_derivatives
    type: interface; text: OES_standard_derivatives
urlPrefix: https://www.khronos.org/registry/webgl/extensions/OES_vertex_array_object/; spec: OES_vertex_array_object
    type: interface; text: OES_vertex_array_object
urlPrefix: https://www.w3.org/TR/geolocation-API/; spec: GEOLOCATION-API
    type: interface
        text: Geolocation; url: geolocation;
        text: Coordinates; url: coordinates;
        text: Position; url: position;
        text: PositionError; url: position-error;
urlPrefix: https://w3c.github.io/deviceorientation/spec-source-orientation.html; spec: ORIENTATION-EVENT
    type: interface
        text: DeviceRotationRate; url: device_rotation_rate;
        text: DeviceAcceleration; url: device_acceleration;
urlPrefix: https://w3c.github.io/mediacapture-main/; spec: MEDIACAPTURE-STREAMS
    type: interface
        text: ConstrainablePattern; url: dom-constrainablepattern;
urlPrefix: http://www.unicode.org/glossary/; spec: UNICODE
    type: dfn
        text: Unicode scalar value; url: unicode_scalar_value
urlPrefix: https://tc39.github.io/ecma262/; spec: ECMA-262
    type: interface; for: ECMAScript
        text: Array; url: sec-array-objects
        text: ArrayBuffer; url: sec-arraybuffer-objects
        text: DataView; url: sec-dataview-objects
        text: Map; url: sec-map-objects
        text: Promise; url: sec-promise-objects
        text: Set; url: sec-set-objects
        text: SharedArrayBuffer; url: sec-sharedarraybuffer-objects
        text: %AsyncIteratorPrototype%; url: sec-asynciteratorprototype
        text: %ErrorPrototype%; url: sec-properties-of-the-error-prototype-object
        text: %FunctionPrototype%; url: sec-properties-of-the-function-prototype-object
        text: %IteratorPrototype%; url: sec-%iteratorprototype%-object
        text: %MapPrototype%; url: sec-properties-of-the-map-prototype-object
        text: %ObjectPrototype%; url: sec-properties-of-the-object-prototype-object
        text: %Promise%; url: sec-promise-constructor
        text: %SetPrototype%; url: sec-properties-of-the-set-prototype-object
    type: exception; for: ECMAScript
        text: Error; url: sec-error-objects
        text: SyntaxError; url: sec-native-error-types-used-in-this-standard-syntaxerror
        text: TypeError; url: sec-native-error-types-used-in-this-standard-typeerror
    type: method; for: ECMAScript
        text: JSON.stringify(); url: sec-json.stringify
        text: %ArrayProto_entries%; url: sec-array.prototype.entries
        text: %ArrayProto_forEach%; url: sec-array.prototype.foreach
        text: %ArrayProto_keys%; url: sec-array.prototype.keys
        text: %ArrayProto_values%; url: sec-array.prototype.values
        text: %ObjProto_toString%; url: sec-object.prototype.tostring
        text: %Promise_reject%; url: sec-promise.reject
        text: %Promise_resolve%; url: sec-promise.resolve
        text: %PromiseProto_then%; url: sec-promise.prototype.then
        text: all(); for: Promise; url: #sec-promise.all
    type: const; for: ECMAScript
        url: sec-well-known-symbols
            text: @@asyncIterator
            text: @@iterator
            text: @@toStringTag
            text: @@unscopables
    type: argument
        text: NewTarget; url: sec-built-in-function-objects
    type: abstract-op
        text: ArrayCreate; url: sec-arraycreate
        text: Call; url: sec-call
        text: CanonicalNumericIndexString; url: sec-canonicalnumericindexstring
        text: Completion; url: sec-completion
        text: Construct; url: sec-construct
        text: CreateArrayIterator; url: sec-createarrayiterator
        text: CreateBuiltinFunction; url: sec-createbuiltinfunction
        text: CreateDataProperty; url: sec-createdataproperty
        text: CreateIterResultObject; url: sec-createiterresultobject
        text: CreateMapIterator; url: sec-createmapiterator
        text: CreateMethodProperty; url: sec-createmethodproperty
        text: CreateSetIterator; url: sec-createsetiterator
        text: DefinePropertyOrThrow; url: sec-definepropertyorthrow
        text: DetachArrayBuffer; url: sec-detacharraybuffer
        for: Environment Record; url: table-15
            text: SetMutableBinding
            text: CreateMutableBinding
            text: InitializeBinding
        text: Get; url: sec-get-o-p
        text: GetFunctionRealm; url: sec-getfunctionrealm
        text: GetIterator; url: sec-getiterator
        text: GetMethod; url: sec-getmethod
        text: IfAbruptRejectPromise; url: sec-ifabruptrejectpromise
        text: IsAccessorDescriptor; url: sec-isaccessordescriptor
        text: IsCallable; url: sec-iscallable
        text: IsConstructor; url: sec-isconstructor
        text: IsDataDescriptor; url: sec-isdatadescriptor
        text: IsDetachedBuffer; url: sec-isdetachedbuffer
        text: IsInteger; url: sec-isinteger
        text: IsSharedArrayBuffer; url: sec-issharedarraybuffer
        text: IteratorStep; url: sec-iteratorstep
        text: IteratorValue; url: sec-iteratorvalue
        text: NewModuleEnvironment; url: sec-newmoduleenvironment
        text: NewPromiseCapability; url: sec-newpromisecapability
        text: NormalCompletion; url: sec-normalcompletion
        text: ObjectCreate; url: sec-objectcreate
        text: OrdinaryDefineOwnProperty; url: sec-ordinarydefineownproperty
        text: OrdinaryGetOwnProperty; url: sec-ordinarygetownproperty
        text: OrdinaryPreventExtensions; url: sec-ordinarypreventextensions
        text: OrdinarySetWithOwnDescriptor; url: sec-ordinarysetwithowndescriptor
        text: PerformPromiseThen; url: sec-performpromisethen
        text: Set; url: sec-set-o-p-v-throw
        text: SetFunctionLength; url: sec-setfunctionlength
        text: SetFunctionName; url: sec-setfunctionname
        text: SetImmutablePrototype; url: sec-set-immutable-prototype
        text: SetIntegrityLevel; url: sec-setintegritylevel
        text: ToBoolean; url: sec-toboolean
        text: ToInt32; url: sec-toint32
        text: ToNumber; url: sec-tonumber
        text: ToObject; url: sec-toobject
        text: ToString; url: sec-tostring
        text: ToUint16; url: sec-touint16
        text: ToUint32; url: sec-touint32
        text: Type; url: sec-ecmascript-data-types-and-values
        text: abs; url: eqn-abs
        text: floor; url: eqn-floor
        text: max; url: eqn-max
        text: min; url: eqn-min
    type: dfn
        text: NumericLiteral; url: sec-literals-numeric-literals
        text: modulo; url: eqn-modulo
        url: sec-returnifabrupt-shorthands
            text: !
            text: ?
        text: ECMA-262 Algorithm Conventions; url: sec-algorithm-conventions
        text: ECMA-262 Ordinary Object Internal Methods and Internal Slots; url: sec-ordinary-object-internal-methods-and-internal-slots
        text: ECMA-262 Built-in Function Objects; url: sec-built-in-function-objects
        text: ECMA-262 Immutable Prototype Exotic Objects; url: sec-immutable-prototype-exotic-objects
        text: abrupt completion; url: sec-completion-record-specification-type
        text: array index; url: array-index
        text: array iterator object; url: sec-array-iterator-objects
        text: built-in function object; url: sec-built-in-function-objects
        text: callable; for: ECMAScript; url: sec-iscallable
        text: Completion Record; url: sec-completion-record-specification-type
        text: constructor; url: constructor
        text: conventions; for: ECMAScript; url: sec-algorithm-conventions
        text: current Realm; url: current-realm
        text: ECMAScript code execution context; url: sec-execution-contexts
        for: ECMAScript code execution context; url: table-23
            text: LexicalEnvironment
            text: VariableEnvironment
        text: element; for: ECMAScript String; url: sec-ecmascript-language-types-string-type
        text: enumerable; url: sec-property-attributes
        text: EnvironmentRecord; for: Lexical Environment; url: sec-lexical-environments
        text: equally close values; url: sec-ecmascript-language-types-number-type
        text: error objects; for: ECMAScript; url: sec-error-objects
        for: Execution context; url: table-22
            text: Function
            text: Realm
            text: ScriptOrModule
        text: execution context stack; url: execution-context-stack
        text: function object; url: function-object
        text: immutable prototype exotic object; url: sec-immutable-prototype-exotic-objects
        url: sec-object-internal-methods-and-internal-slots
            text: internal method
            text: internal slot
        text: Module Record; url: sec-abstract-module-records
        text: Module Record Fields; url: table-36
        text: Number type; url: sec-ecmascript-language-types-number-type
        text: Object; for: ECMAScript; url: sec-object-type
        for: ordinary object; url: sec-ordinary-object-internal-methods-and-internal-slots
            text: internal method
            text: internal slot
        text: own property; url: sec-own-property
        text: PromiseCapability; url: sec-promisecapability-records
        text: Property Descriptor; url: sec-property-descriptor-specification-type
        text: Source Text Module Record; url: sourctextmodule-record
        text: realm; url: realm
        text: ResolvedBinding Record; url: resolvedbinding-record
        text: running execution context; url: running-execution-context
</pre>

<pre class=biblio>
{
    "GEOMETRY": {
        "aliasOf": "GEOMETRY-1"
    },
    "JSSTDLIB": {
        "href": "https://github.com/tc39/proposal-javascript-standard-library/",
        "title": "Standard Library Proposal"
    }
}
</pre>

<style>
        pre.set {
          font-size: 80%;
        }

        .syntax .n,
        .syntax .nv {
          font-style: italic;
        }

        .mute,
        .deprecated,
        .deprecated a,
        .deprecated code {
          color: #9D937D;
        }

        .deprecated a:visited,
        .deprecated a {
            border-bottom-color: #9D937D;
        }

        emu-const {
            font-family: sans-serif;
        }

        emu-val {
            font-weight: bold;
        }

        emu-nt {
            font-family: sans-serif;
            font-style: italic;
            white-space: nowrap;
        }

        emu-t {
            font-family: Menlo, Consolas, "DejaVu Sans Mono", Monaco, monospace;
            font-weight: bold;
            white-space: nowrap;
        }

        emu-t.regex {
            font-family: sans-serif;
            font-weight: bold;
        }

        emu-t a[href],
        emu-nt a[href] {
            color: inherit;
            border-bottom: 1px solid transparent;
        }

        emu-t a[href]:focus,
        emu-nt a[href]:focus,
        emu-t a[href]:hover,
        emu-nt a[href]:hover {
            background: #f8f8f8;
            background: rgba(75%, 75%, 75%, .25);
            border-bottom: 3px solid #707070;
            margin-bottom: -2px;
        }

        /* start bug fix, see: https://github.com/tobie/webidl/issues/24 */
        pre.grammar {
            padding-bottom: 1px
        }
        /* end bug fix */

        dt p {
            display: inline;
        }

        .char {
            font-size: 85%
        }

        #distinguishable-table {
          font-size: 80%;
          border-collapse: collapse;
          width: auto;
        }

        #distinguishable-table th {
          text-align: right;
        }

        #distinguishable-table tr:first-child th {
          white-space: nowrap;
          text-align: center;
        }

        #distinguishable-table .belowdiagonal {
          background: #ddd;
        }

        #distinguishable-table td {
          text-align: center;
          padding: 5px 10px;
        }

        .csstransforms #distinguishable-table tr:first-child th {
          text-align: left;
          border: none;
          height: 100px;
          padding: 0;
        }

        .csstransforms #distinguishable-table td {
          text-align: center;
          width: 30px;
          min-width: 30px;
          padding: 10px 5px;
          height: 19px
        }

        /* Firefox needs the extra DIV for some reason, otherwise the text disappears if you rotate */
        .csstransforms #distinguishable-table tr:first-child th div {
          -webkit-transform: translate(26px, 31px) rotate(315deg);
          transform: translate(26px, 31px) rotate(315deg);
          width: 30px;
        }

        .csstransforms #distinguishable-table tr:first-child th div span {
          border-bottom: 1px solid #ccc;
          padding: 5px 10px;
          display: block;
          min-width: 120px;
          text-align: left
        }

        .csstransforms #distinguishable-table tr:first-child th:last-child div span {
          border-bottom: none;
        }

        #toc .current,
        #toc .current-parent {
          border-right-width: 3px;
          border-right-style: solid;
          border-right-color: #3980B5;
        }

        #toc .current {
          background: rgba(75%, 75%, 75%, .25);
          border-right-color: #054572;
        }
</style>

<div boilerplate=status>
<p>
  This is a public copy of the editors’ draft.
  It is provided for discussion only and may change at any moment.
  Its publication here does not imply endorsement of its contents
  by <abbr title="World Wide Web Consortium">W3C</abbr>.
  Don’t cite this document other than as work in progress.

<p>
  <strong>Changes to this document may be tracked at
  <a href="[REPOSITORYURL]">[REPOSITORYURL]</a>.</strong>

<p>
  <a href="[REPOSITORYURL]/issues">GitHub issues</a> are preferred for discussion of this specification.
  There is also a <a href="[MAILINGLISTARCHIVES]">historical mailing-list archive</a>.

<p>
  This document was produced by the
  <a href="https://www.w3.org/WebPlatform/WG/">Web Platform Working Group</a>.

<p>
  This document was produced by a group operating under the
  <a href="https://www.w3.org/Consortium/Patent-Policy-20040205/">5 February 2004
  <abbr title="World Wide Web Consortium">W3C</abbr> Patent Policy</a>.
  <abbr title="World Wide Web Consortium">W3C</abbr> maintains a
  <a href="https://www.w3.org/2004/01/pp-impl/83482/status" rel="disclosure">public list of any patent disclosures</a>
  made in connection with the deliverables of the group;
  that page also includes instructions for disclosing a patent.
  An individual who has actual knowledge of a patent which the individual believes contains
  <a href="https://www.w3.org/Consortium/Patent-Policy-20040205/#def-essential">Essential Claim(s)</a>
  must disclose the information in accordance with
  <a href="https://www.w3.org/Consortium/Patent-Policy-20040205/#sec-Disclosure">section 6 of the
  <abbr title="World Wide Web Consortium">W3C</abbr> Patent Policy</a>.

<p>
    This document is governed by the
    <a href="https://www.w3.org/2017/Process-20170301/">1 March 2017
    <abbr title="World Wide Web Consortium">W3C</abbr> Process Document</a>.

<p>
  [STATUSTEXT]

</div>


<h2 id="introduction">Introduction</h2>

<i>This section is informative.</i>

Technical reports published by the W3C that include programming
language interfaces have typically been described using the
Object Management Group’s Interface Definition Language (IDL)
[[OMGIDL]].  The IDL provides a means to
describe these interfaces in a language independent manner.  Usually,
additional language binding appendices are included in such
documents which detail how the interfaces described with the IDL
correspond to constructs in the given language.

However, the bindings in these specifications for the language most
commonly used on the web, ECMAScript, are consistently specified with
low enough precision as to result in interoperability issues.  In
addition, each specification must describe the same basic information,
such as DOM interfaces described in IDL corresponding to properties
on the ECMAScript global object, or the {{unsigned long}} IDL type mapping to the Number
type in ECMAScript.

This specification defines an IDL language similar to OMG IDL
for use by specifications that define interfaces for Web APIs.  A number of extensions are
given to the IDL to support common functionality that previously must
have been written in prose.  In addition, precise language bindings
for the ECMAScript language are given.


<h2 id="idl">Interface definition language</h2>

This section describes a language, <em>Web IDL</em>, which can be used to define
interfaces for APIs in the Web platform.  A specification that defines Web APIs
can include one or more <dfn id="dfn-idl-fragment" export lt="IDL fragment">IDL fragments</dfn> that
describe the interfaces (the state and behavior that objects can exhibit)
for the APIs defined by that specification.
An [=IDL fragment=] is
a sequence of definitions that matches the <emu-nt><a href="#prod-Definitions">Definitions</a></emu-nt> grammar symbol.
The set of [=IDL fragments=] that
an implementation supports is not ordered.
See [[#idl-grammar]] for the complete grammar and an explanation of the notation used.

The different kinds of <dfn id="dfn-definition">definitions</dfn> that can appear in an
[=IDL fragment=] are:
[=interfaces=],
[=partial interface|partial interface definitions=],
[=interface mixins=],
[=partial interface mixin|partial mixin definitions=],
[=callback functions=],
[=callback interfaces=],
[=namespaces=],
[=partial namespace|partial namespace definitions=],
[=dictionary|dictionaries=],
[=partial dictionary|partial dictionary definitions=],
[=typedefs=] and
[=includes statements=].
These are all defined in the following sections.

Each [=definition=]
(matching <emu-nt><a href="#prod-Definition">Definition</a></emu-nt>)
can be preceded by a list of [=extended attributes=] (matching
<emu-nt><a href="#prod-ExtendedAttributeList">ExtendedAttributeList</a></emu-nt>),
which can control how the definition will be handled in language bindings.
The extended attributes defined by this specification that are language binding
agnostic are discussed in [[#idl-extended-attributes]],
while those specific to the ECMAScript language binding are discussed
in [[#es-extended-attributes]].

<pre highlight="webidl" class="syntax">
    [<mark>extended_attributes</mark>]
    interface identifier {
      /* interface_members... */
    };
</pre>

<pre class="grammar" id="prod-Definitions">
    Definitions :
        ExtendedAttributeList Definition Definitions
        ε
</pre>

<pre class="grammar" id="prod-Definition">
    Definition :
        CallbackOrInterfaceOrMixin
        Namespace
        Partial
        Dictionary
        Enum
        Typedef
        IncludesStatement
</pre>

<div class="example">

    The following is an example of an [=IDL fragment=].

    <pre highlight="webidl">
        [Exposed=Window]
        interface Paint { };

        [Exposed=Window]
        interface SolidColor : Paint {
          attribute double red;
          attribute double green;
          attribute double blue;
        };

        [Exposed=Window]
        interface Pattern : Paint {
          attribute DOMString imageURL;
        };

        [Exposed=Window]
        interface GraphicalWindow {
          constructor();
          readonly attribute unsigned long width;
          readonly attribute unsigned long height;

          attribute Paint currentPaint;

          void drawRectangle(double x, double y, double width, double height);

          void drawText(double x, double y, DOMString text);
        };
    </pre>

    Here, four [=interfaces=]
    are being defined.
    The <code class="idl">GraphicalWindow</code> interface has two
    [=read only=] [=attributes=],
    one writable attribute, and two [=operations=]
    defined on it.  Objects that implement the <code class="idl">GraphicalWindow</code> interface
    will expose these attributes and operations in a manner appropriate to the
    particular language being used.

    In ECMAScript, the attributes on the IDL interfaces will be exposed as accessor
    properties and the operations as data properties whose value is a [=built-in function object=] on a
    prototype object for all <code class="idl">GraphicalWindow</code>
    objects; each ECMAScript object that implements <code class="idl">GraphicalWindow</code>
    will have that prototype object in its prototype chain.

    The [=constructor operation=] that appears on <code class="idl">GraphicalWindow</code>
    causes a [=constructor=] to exist in ECMAScript implementations,
    so that calling <code>new GraphicalWindow()</code> would return a new object
    that implemented the interface.

    All [=interfaces=] have the [{{Exposed}}] [=extended attribute=], which ensures the interfaces
    are only available in [=Realms=] whose [=Realm/global object=] is a {{Window}} object.
</div>


<h3 id="idl-names">Names</h3>

Every [=interface=],
[=partial interface|partial interface definition=],
[=namespace=],
[=partial namespace|partial namespace definition=],
[=dictionary=],
[=partial dictionary|partial dictionary definition=],
[=enumeration=],
[=callback function=],
[=callback interface=] and
[=typedef=] (together called <dfn id="dfn-named-definition" export lt="named definition">named definitions</dfn>)
and every [=constant=],
[=attribute=],
and [=dictionary member=] has an
<dfn id="dfn-identifier" export>identifier</dfn>, as do some
[=operations=].
The identifier is determined by an
<emu-t class="regex"><a href="#prod-identifier">identifier</a></emu-t> token somewhere
in the declaration:

*   For [=named definitions=],
    the <emu-t class="regex"><a href="#prod-identifier">identifier</a></emu-t> token that appears
    directly after the <emu-t>interface</emu-t>, <emu-t>namespace</emu-t>,
    <emu-t>dictionary</emu-t>, <emu-t>enum</emu-t>
    or <emu-t>callback</emu-t> keyword
    determines the identifier of that definition.
    <pre highlight="webidl" class="syntax">
        interface <mark>interface_identifier</mark> { /* interface_members... */ };
        partial interface <mark>interface_identifier</mark> { /* interface_members... */ };
        namespace <mark>namespace_identifier</mark> { /* namespace_members... */ };
        partial namespace <mark>namespace_identifier</mark> { /* namespace_members... */ };
        dictionary <mark>dictionary_identifier</mark> { /* dictionary_members... */ };
        partial dictionary <mark>dictionary_identifier</mark> { /* dictionary_members... */ };
        enum <mark>enumeration_identifier</mark> { "enum", "values" /* , ... */ };
        callback <mark>callback_identifier</mark> = return_type (/* arguments... */);
        callback interface <mark>callback_interface_identifier</mark> { /* interface_members... */ };
    </pre>
*   For [=attributes=],
    [=typedefs=]
    and [=dictionary members=],
    the final <emu-t class="regex"><a href="#prod-identifier">identifier</a></emu-t> token before the
    semicolon at the end of the declaration determines the identifier.
    <pre highlight="webidl" class="syntax">
        [extended_attributes]
        interface identifier {
          attribute type <mark>attribute_identifier</mark>;
        };

        typedef type <mark>typedef_identifier</mark>;

        dictionary identifier {
          type <mark>dictionary_member_identifier</mark>;
        };
    </pre>
*   For [=constants=],
    the <emu-t class="regex"><a href="#prod-identifier">identifier</a></emu-t> token before the
    equals sign determines the identifier.
    <pre highlight="webidl" class="syntax">const type <mark>constant_identifier</mark> = 42;</pre>
*   For [=operations=], the
    <emu-t class="regex"><a href="#prod-identifier">identifier</a></emu-t> token that appears
    after the return type but before the opening parenthesis (that is,
    one that is matched as part of the <emu-nt><a href="#prod-OptionalOperationName">OptionalOperationName</a></emu-nt>
    grammar symbol in an <emu-nt><a href="#prod-OperationRest">OperationRest</a></emu-nt>) determines the identifier of the operation.  If
    there is no such <emu-t class="regex"><a href="#prod-identifier">identifier</a></emu-t> token,
    then the operation does not have an identifier.
    <pre highlight="webidl" class="syntax">
        interface interface_identifier {
          return_type <mark>operation_identifier</mark>(/* arguments... */);
        };
    </pre>

Note: Operations can have no identifier when they are being used to declare a
[=special operation|special kind of operation=], such as a getter or setter.

For all of these constructs, the [=identifier=]
is the value of the <emu-t class="regex"><a href="#prod-identifier">identifier</a></emu-t> token with any leading
<span class="char">U+005F LOW LINE ("_")</span> character (underscore) removed.

Note: A leading <span class="char">"_"</span> is used to escape an identifier from looking
like a reserved word so that, for example, an interface named "<code>interface</code>" can be
defined.  The leading <span class="char">"_"</span> is dropped to unescape the
identifier.

Operation arguments can take a slightly wider set of identifiers.  In an operation
declaration, the identifier of an argument is specified immediately after its
type and is given by either an <emu-t class="regex"><a href="#prod-identifier">identifier</a></emu-t>
token or by one of the keywords that match the <emu-nt><a href="#prod-ArgumentNameKeyword">ArgumentNameKeyword</a></emu-nt>
symbol.  If one of these keywords is used, it need not be escaped with a leading
underscore.

<pre highlight="webidl" class="syntax">
    interface interface_identifier {
      return_type operation_identifier(argument_type <mark>argument_identifier</mark> /* , ... */);
    };
</pre>

<pre class="grammar" id="prod-ArgumentNameKeyword">
    ArgumentNameKeyword :
        "async"
        "attribute"
        "callback"
        "const"
        "constructor"
        "deleter"
        "dictionary"
        "enum"
        "getter"
        "includes"
        "inherit"
        "interface"
        "iterable"
        "maplike"
        "mixin"
        "namespace"
        "partial"
        "readonly"
        "required"
        "setlike"
        "setter"
        "static"
        "stringifier"
        "typedef"
        "unrestricted"
</pre>

If an <emu-t class="regex"><a href="#prod-identifier">identifier</a></emu-t> token is used, then the
[=identifier=] of the operation argument
is the value of that token with any leading
<span class="char">U+005F LOW LINE ("_")</span> character (underscore) removed.
If instead one of the <emu-nt><a href="#prod-ArgumentNameKeyword">ArgumentNameKeyword</a></emu-nt>
keyword token is used, then the [=identifier=] of the operation argument
is simply that token.

The [=identifier=] of any of the abovementioned
IDL constructs (except operation arguments) must not be "<code>constructor</code>",
"<code>toString</code>",
or begin with a <span class="char">U+005F LOW LINE ("_")</span> character.  These
are known as <dfn id="dfn-reserved-identifier" export>reserved identifiers</dfn>.

Although the "<code>toJSON</code>" [=identifier=] is not a [=reserved identifier=],
it must only be used for [=regular operations=]
that convert objects to [=JSON types=],
as described in [[#idl-tojson-operation]].

Note: Further restrictions on identifier names for particular constructs may be made
in later sections.

Within the set of [=IDL fragments=]
that a given implementation supports,
the [=identifier=] of every
[=interface=],
[=namespace=],
[=dictionary=],
[=enumeration=],
[=callback function=],
[=callback interface=] and
[=typedef=]
must not
be the same as the identifier of any other
[=interface=],
[=namespace=],
[=dictionary=],
[=enumeration=],
[=callback function=],
[=callback interface=] or
[=typedef=].

Within an [=IDL fragment=], a reference
to a [=definition=] need not appear after
the declaration of the referenced definition.  References can also be made
across [=IDL fragments=].

<div class="example">

    Therefore, the following [=IDL fragment=] is valid:

    <pre highlight="webidl">
        [Exposed=Window]
        interface B : A {
          void f(SequenceOfLongs x);
        };

        [Exposed=Window]
        interface A {
        };

        typedef sequence&lt;long&gt; SequenceOfLongs;
    </pre>
</div>

<div class="example">

    The following [=IDL fragment=]
    demonstrates how [=identifiers=]
    are given to definitions and [=interface members=].

    <pre highlight="webidl">
        // Typedef identifier: "number"
        typedef double number;

        // Interface identifier: "System"
        [Exposed=Window]
        interface System {

          // Operation identifier:          "createObject"
          // Operation argument identifier: "interface"
          object createObject(DOMString _interface);

          // Operation argument identifier: "interface"
          sequence&lt;object&gt; getObjects(DOMString interface);

          // Operation has no identifier; it declares a getter.
          getter DOMString (DOMString keyName);
        };

        // Interface identifier: "TextField"
        [Exposed=Window]
        interface TextField {

          // Attribute identifier: "const"
          attribute boolean _const;

          // Attribute identifier: "value"
          attribute DOMString? _value;
        };
    </pre>

    Note that while the second [=attribute=]
    on the <code class="idl">TextField</code> [=interface=]
    need not have been escaped with an underscore (because "<code>value</code>" is
    not a keyword in the IDL grammar), it is still unescaped
    to obtain the attribute’s [=identifier=].

</div>


<h3 id="idl-interfaces">Interfaces</h3>

[=IDL fragments=] are used to
describe object oriented systems.  In such systems, objects are entities
that have identity and which are encapsulations of state and behavior.
An <dfn id="dfn-interface" export>interface</dfn> is a definition (matching
<emu-t>interface</emu-t> <emu-nt><a href="#prod-InterfaceRest">InterfaceRest</a></emu-nt>) that declares some
state and behavior that an object implementing that interface will expose.

<pre highlight="webidl" class="syntax">
    [extended_attributes]
    interface identifier {
      /* interface_members... */
    };
</pre>

An interface is a specification of a set of
<dfn id="dfn-interface-member" export lt="interface member">interface members</dfn>
(matching <emu-nt><a href="#prod-InterfaceMembers">InterfaceMembers</a></emu-nt>).
These are the [=members=] that appear between the braces in the interface declaration.

Interfaces in Web IDL describe how objects that implement the
interface behave.  In bindings for object oriented languages, it is
expected that an object that implements a particular IDL interface
provides ways to inspect and modify the object's state and to
invoke the behavior described by the interface.

An interface can be defined to <dfn id="dfn-inherit" for="interface" export>inherit</dfn> from another interface.
If the identifier of the interface is followed by a
<span class="char">U+003A COLON (":")</span> character
and an [=identifier=],
then that identifier identifies the inherited interface.
An object that implements an interface that inherits from another
also implements that inherited interface.  The object therefore will also
have members that correspond to the interface members from the inherited interface.

<pre highlight="webidl" class="syntax">
    interface identifier : <mark>identifier_of_inherited_interface</mark> {
      /* interface_members... */
    };
</pre>

The order that members appear in has significance for property enumeration in the <a href="#es-interfaces">ECMAScript binding</a>.

Interfaces may specify an interface member that has the same name as
one from an inherited interface.  Objects that implement the derived
interface will expose the member on the derived interface.  It is
language binding specific whether the overridden member can be
accessed on the object.

<div class="example">

    Consider the following two interfaces.

    <pre highlight="webidl">
        [Exposed=Window]
        interface A {
          void f();
          void g();
        };

        [Exposed=Window]
        interface B : A {
          void f();
          void g(DOMString x);
        };
    </pre>

    In the ECMAScript language binding, an instance of <code class="idl">B</code>
    will have a prototype chain that looks like the following:

    <pre>
        [Object.prototype: the Object prototype object]
             ↑
        [A.prototype: interface prototype object for A]
             ↑
        [B.prototype: interface prototype object for B]
             ↑
        [instanceOfB]
    </pre>

    Calling <code>instanceOfB.f()</code> in ECMAScript will invoke the f defined
    on <code class="idl">B</code>.  However, the f from <code class="idl">A</code>
    can still be invoked on an object that implements <code class="idl">B</code> by
    calling <code>A.prototype.f.call(instanceOfB)</code>.

</div>

The <dfn id="dfn-inherited-interfaces" export>inherited interfaces</dfn> of
a given interface |A| is the set of all interfaces that |A|
inherits from, directly or indirectly.  If |A| does not [=interface/inherit=]
from another interface, then the set is empty.  Otherwise, the set
includes the interface |B| that |A| [=interface/inherits=]
from and all of |B|’s [=inherited interfaces=].

An interface must not be declared such that
its inheritance hierarchy has a cycle.  That is, an interface
|A| cannot inherit from itself, nor can it inherit from another
interface |B| that inherits from |A|, and so on.

<div algorithm>
  The [=list=] of <dfn for=interface>inclusive inherited interfaces</dfn> of an [=interface=] |I|
  is defined as follows:

    1.  Let |result| be « ».
    1.  Let |interface| be |I|.
    1.  While |interface| is not null:
        1.  [=list/Append=] |interface| to |result|.
        1.  Set |interface| to the [=interface=] that |I| [=interface/inherits=] from, if any, and
            null otherwise.
    1.  Return |result|.
</div>

Note that general multiple inheritance of interfaces is not supported, and
objects also cannot implement arbitrary sets of interfaces.
Objects can be defined to implement a single given interface |A|,
which means that it also implements all of |A|’s [=inherited interfaces=].
In addition, an [=includes statement=] can be used
to define that objects implementing an [=interface=] |A|
will always also include the [=interface mixin member|members=]
of the [=interface mixins=] |A| [=includes=].

Each interface member can be preceded by a list of [=extended attributes=] (matching
<emu-nt><a href="#prod-ExtendedAttributeList">ExtendedAttributeList</a></emu-nt>),
which can control how the interface member will be handled in language bindings.

<pre highlight="webidl" class="syntax">
    [extended_attributes]
    interface identifier {

      [<mark>extended_attributes</mark>]
      const type constant_identifier = 42;

      [<mark>extended_attributes</mark>]
      attribute type identifier;

      [<mark>extended_attributes</mark>]
      return_type identifier(/* arguments... */);
    };
</pre>

The IDL for interfaces can be split into multiple parts by using
<dfn id="dfn-partial-interface" export>partial interface</dfn> definitions
(matching <emu-t>partial</emu-t> <emu-t>interface</emu-t>
<emu-nt><a href="#prod-PartialInterfaceRest">PartialInterfaceRest</a></emu-nt>).
The [=identifier=] of a partial
interface definition must be the same
as the identifier of an interface definition.  All of
the members that appear on each of the partial interfaces are considered to be
members of the interface itself.

<pre highlight="webidl" class="syntax">
    interface <mark>SomeInterface</mark> {
      /* interface_members... */
    };

    partial interface <mark>SomeInterface</mark> {
      /* interface_members... */
    };
</pre>

Note: Partial interface definitions are intended for use as a specification
editorial aide, allowing the definition of an interface to be separated
over more than one section of the document, and sometimes multiple documents.

The order of appearance of an [=interface=]
definition and any of its [=partial interface=]
definitions does not matter.

Note: A partial interface definition cannot specify that the interface
[=interface/inherits=] from another interface.
Inheritance must be specified on the original [=interface=]
definition.

The relevant language binding determines how interfaces correspond to constructs
in the language.

The following extended attributes are applicable to interfaces:
[{{Exposed}}],
[{{Global}}],
[{{LegacyWindowAlias}}],
[{{NamedConstructor}}],
[{{NoInterfaceObject}}],
[{{OverrideBuiltins}}], and
[{{SecureContext}}].

The following extended attributes are applicable to [=partial interfaces=]:
[{{Exposed}}],
[{{OverrideBuiltins}}], and
[{{SecureContext}}].

[=Interfaces=] which are not annotated
with a [{{NoInterfaceObject}}] [=extended attribute=]
must be annotated with an [{{Exposed}}] [=extended attribute=].

<div algorithm>

The <dfn>qualified name</dfn> of an [=interface=] |interface| is defined as follows:

1.  Let |identifier| be the [=identifier=] of |interface|.
1.  If |interface| has a [{{LegacyNamespace}}] [=extended attribute=], then:
    1.  Let |namespace| be the identifier argument of the [{{LegacyNamespace}}]
        [=extended attribute=].
    1.  Return the [=concatenation=] of « |namespace|, |identifier| » with
        separator <span class="char">U+002E FULL STOP (".")</span>.
1. Return |identifier|.

</div>

<pre class="grammar" id="prod-CallbackOrInterfaceOrMixin">
    CallbackOrInterfaceOrMixin :
        "callback" CallbackRestOrInterface
        "interface" InterfaceOrMixin
</pre>

<pre class="grammar" id="prod-InterfaceOrMixin">
    InterfaceOrMixin :
        InterfaceRest
        MixinRest
</pre>

<pre class="grammar" id="prod-InterfaceRest">
    InterfaceRest :
        identifier Inheritance "{" InterfaceMembers "}" ";"
</pre>

<pre class="grammar" id="prod-Partial">
    Partial :
        "partial" PartialDefinition
</pre>

<pre class="grammar" id="prod-PartialDefinition">
    PartialDefinition :
        "interface" PartialInterfaceOrPartialMixin
        PartialDictionary
        Namespace
</pre>

<pre class="grammar" id="prod-PartialInterfaceOrPartialMixin">
    PartialInterfaceOrPartialMixin :
        PartialInterfaceRest
        MixinRest
</pre>

<pre class="grammar" id="prod-PartialInterfaceRest">
    PartialInterfaceRest :
        identifier "{" PartialInterfaceMembers "}" ";"
</pre>

<pre class="grammar" id="prod-InterfaceMembers">
    InterfaceMembers :
        ExtendedAttributeList InterfaceMember InterfaceMembers
        ε
</pre>

<pre class="grammar" id="prod-InterfaceMember">
    InterfaceMember :
        PartialInterfaceMember
        Constructor
</pre>

<pre class="grammar" id="prod-PartialInterfaceMembers">
    PartialInterfaceMembers :
        ExtendedAttributeList PartialInterfaceMember PartialInterfaceMembers
        ε
</pre>

<pre class="grammar" id="prod-PartialInterfaceMember">
    PartialInterfaceMember :
        Const
        Operation
        Stringifier
        StaticMember
        Iterable
        AsyncIterable
        ReadOnlyMember
        ReadWriteAttribute
        ReadWriteMaplike
        ReadWriteSetlike
</pre>

<pre class="grammar" id="prod-Inheritance">
    Inheritance :
        ":" identifier
        ε
</pre>

<div class="example">

    The following [=IDL fragment=]
    demonstrates the definition of two mutually referential [=interfaces=].
    Both <code class="idl">Human</code> and <code class="idl">Dog</code>
    inherit from <code class="idl">Animal</code>.  Objects that implement
    either of those two interfaces will thus have a <code>name</code> attribute.

    <pre highlight="webidl">
        [Exposed=Window]
        interface Animal {
          attribute DOMString name;
        };

        [Exposed=Window]
        interface Human : Animal {
          attribute Dog? pet;
        };

        [Exposed=Window]
        interface Dog : Animal {
          attribute Human? owner;
        };
    </pre>
</div>

<div class="example">

    The following [=IDL fragment=] defines
    simplified versions of a DOM [=interfaces=]
    and a [=callback interface=].

    <pre highlight="webidl">
        [Exposed=Window]
        interface Node {
          readonly attribute DOMString nodeName;
          readonly attribute Node? parentNode;
          Node appendChild(Node newChild);
          void addEventListener(DOMString type, EventListener listener);
        };

        callback interface EventListener {
          void handleEvent(Event event);
        };
    </pre>

    Plain objects can implement a [=callback interface=] like
    <code class="idl">EventListener</code>:

    <pre highlight="js">
        var node = getNode();                                // Obtain an instance of Node.

        var listener = {
          handleEvent: function(event) {
            // ...
          }
        };
        node.addEventListener("click", listener);            // This works.

        node.addEventListener("click", function() { ... });  // As does this.
    </pre>

    It is not possible for such an object to implement an [=interface=] like
    <code class="idl">Node</code>, however:

    <pre highlight="js">
        var node = getNode();  // Obtain an instance of Node.

        var newNode = {
          nodeName: "span",
          parentNode: null,
          appendChild: function(newchild) {
            // ...
          },
          addEventListener: function(type, listener) {
            // ...
          }
        };
        node.appendChild(newNode);  // This will throw a TypeError exception.
    </pre>
</div>


<h3 id="idl-interface-mixins">Interface mixins</h3>

An <dfn export>interface mixin</dfn> is a definition (matching <emu-t>interface</emu-t> <emu-nt><a href="#prod-MixinRest">MixinRest</a></emu-nt>)
that declares state and behavior that can be [=included=] by one or more [=interfaces=],
and that are exposed by objects that implement an [=interface=]
that [=includes=] the [=interface mixin=].

<pre highlight="webidl" class="syntax">
    interface mixin identifier {
      /* mixin_members... */
    };
</pre>

Note: [=Interface mixins=], much like [=partial interfaces=],
are intended for use as a specification editorial aide,
allowing a coherent set of functionalities to be grouped together,
and included in multiple interfaces, possibly across documents.
They are not meant to be exposed through language bindings.
Guidance on when to choose [=partial interfaces=], [=interface mixins=],
or [=partial interface mixins=] can be found in [[#using-mixins-and-partials]].

An [=interface mixin=] is a specification of a set of <dfn export lt="interface mixin member">interface mixin members</dfn>
(matching <emu-nt><a href="#prod-MixinMembers">MixinMembers</a></emu-nt>),
which are the [=constants=], [=regular operations=], [=regular attributes=], and [=stringifiers=]
that appear between the braces in the [=interface mixin=] declaration.

These [=constants=], [=regular operations=], [=regular attributes=], and [=stringifiers=]
describe the behaviors that can be implemented by an object,
as if they were specified on the [=interface=] that [=includes=] them.

[=Static attributes=], [=static operations=], [=special operations=] except for [=stringifiers=], and
[=iterable declaration|iterable=], [=asynchronously iterable declaration|asynchronously iterable=],
[=maplike declaration|maplike=], and [=setlike declarations=] cannot appear in [=interface mixin=]
declarations.

As with interfaces, the IDL for [=interface mixins=] can be split into multiple parts by using
<dfn export>partial interface mixin</dfn> definitions
(matching <emu-t>partial</emu-t> <emu-t>interface</emu-t> <emu-nt><a href="#prod-MixinRest">MixinRest</a></emu-nt>).
The [=identifier=] of a [=partial interface mixin=] [=definition=] must
be the same as the [=identifier=] of an [=interface mixin=] [=definition=].
All of the [=interface mixin member|members=] that appear on each of the [=partial interface mixin=] [=definitions=]
are considered to be [=members=] of the [=interface mixin=] itself,
and—by extension—of the [=interfaces=] that [=include=] the [=interface mixin=].

<pre highlight="webidl" class="syntax">
    interface mixin <mark>SomeMixin</mark> {
      /* mixin_members... */
    };

    partial interface mixin <mark>SomeMixin</mark> {
      /* mixin_members... */
    };
</pre>

The order that members appear in has significance for property enumeration
in the <a href="#es-namespaces">ECMAScript binding</a>.

Note that unlike [=interfaces=] or [=dictionaries=], [=interface mixins=] do not create types.

Of the extended attributes defined in this specification,
only the [{{Exposed}}] and [{{SecureContext}}] extended attributes
are applicable to [=interface mixins=].

An <dfn>includes statement</dfn> is a definition
(matching <emu-nt><a href="#prod-IncludesStatement">IncludesStatement</a></emu-nt>)
used to declare that all objects implementing an [=interface=] |I|
(identified by the first [=identifier=])
must additionally include the [=interface mixin member|members=] of [=interface mixin=] |M|
(identified by the second identifier).
[=Interface=] |I| is said to <dfn id="include" for="interface" export>include</dfn>
[=interface mixin=] |M|.

<pre highlight="webidl" class="syntax">
    interface_identifier includes mixin_indentifier;
</pre>

The first [=identifier=] must reference a [=interface=] |I|.
The second identifier must reference an [=interface mixin=] |M|.

Each [=interface mixin member|member=] of |M| is considered to be
a [=member=] of each [=interface=] |I|, |J|, |K|, … that [=includes=] |M|,
as if a copy of each [=interface mixin member|member=] had been made.
So for a given member <var ignore>m</var> of |M|,
interface |I| is considered to have a [=member=] <var>m<sub>I</sub></var>,
interface |J| is considered to have a [=member=] <var>m<sub>J</sub></var>,
interface |K| is considered to have a [=member=] <var>m<sub>K</sub></var>, and so on.
The <dfn>host interfaces</dfn> of <var>m<sub>I</sub></var>, <var>m<sub>J</sub></var>,
and <var>m<sub>K</sub></var>, are |I|, |J|, and |K| respectively.

Note: In ECMAScript, this implies that each [=regular operation=]
declared as a [=interface mixin member|member=] of [=interface mixin=] |M|,
and exposed as a data property with a [=built-in function object=] value,
is a distinct [=built-in function object=]
in each [=interface prototype object=]
whose associated [=interface=] [=includes=] |M|.
Similarly, for [=attributes=], each copy of the accessor property has
distinct [=built-in function objects=] for its getters and setters.

The order of appearance of [=includes statements=] affects the order in which [=interface mixin=]
are [=included=] by their [=host interface=].

Issue: [=interface mixin member|Member=] order isn't clearly specified,
in particular when [=interface mixins=] are defined in separate documents.
It is discussed in <a href="https://github.com/heycam/webidl/issues/432">issue #432</a>.

No [=extended attributes=] defined in this specification are applicable to [=includes statements=].

<div class="example" id="example-mixin">

    The following [=IDL fragment=] defines an [=interface=], <code class="idl">Entry</code>,
    and an [=interface mixin=], <code class="idl">Observable</code>.
    The [=includes statement=] specifies that
    <code class="idl">Observable</code>'s [=interface mixin member|members=]
    are always included on objects implementing <code class="idl">Entry</code>.

    <pre highlight="webidl">
        interface Entry {
          readonly attribute unsigned short entryType;
          // ...
        };

        interface mixin Observable {
          void addEventListener(DOMString type,
                                EventListener listener,
                                boolean useCapture);
          // ...
        };

        Entry includes Observable;
    </pre>

    An ECMAScript implementation would thus have an <code class="idl">addEventListener</code>
    property in the prototype chain of every <code class="idl">Entry</code>:

    <pre highlight="js">
        var e = getEntry();          // Obtain an instance of Entry.
        typeof e.addEventListener;   // Evaluates to "function".
    </pre>

</div>

<div data-fill-with="grammar-CallbackOrInterfaceOrMixin"></div>

<div data-fill-with="grammar-CallbackRestOrInterfaceOrMixin"></div>

<div data-fill-with="grammar-InterfaceOrMixin"></div>

<div data-fill-with="grammar-Partial"></div>

<div data-fill-with="grammar-PartialDefinition"></div>

<pre class="grammar" id="prod-MixinRest">
    MixinRest :
        "mixin" identifier "{" MixinMembers "}" ";"
</pre>

<pre class="grammar" id="prod-MixinMembers">
    MixinMembers :
        ExtendedAttributeList MixinMember MixinMembers
        ε
</pre>

<pre class="grammar" id="prod-MixinMember">
    MixinMember :
        Const
        RegularOperation
        Stringifier
        ReadOnly AttributeRest
</pre>

<pre class="grammar" id="prod-IncludesStatement">
    IncludesStatement :
        identifier "includes" identifier ";"
</pre>

<h4 id="using-mixins-and-partials">Using mixins and partials</h4>

<i>This section is informative.</i>

[=Interface mixins=] allow the sharing of [=attributes=], [=constants=], and [=operations=]
across <em>multiple</em> [=interfaces=].
If you're only planning to extend a single interface,
you might consider using a [=partial interface=] instead.

For example, instead of:

<pre highlight="webidl">
    interface mixin WindowSessionStorage {
      readonly attribute Storage sessionStorage;
    };
    Window includes WindowSessionStorage;
</pre>

do:

<pre highlight="webidl">
    partial interface Window {
      readonly attribute Storage sessionStorage;
    };
</pre>

Additionally, you can rely on extending [=interface mixins=] exposed by other specifications
to target common use cases, such as [=exposed|exposing=]
a set of [=attributes=], [=constants=], or [=operations=]
across both window and worker contexts.

For example, instead of the common but verbose:

<pre highlight="webidl">
    interface mixin GlobalCrypto {
      readonly attribute Crypto crypto;
    };

    Window includes GlobalCrypto;
    WorkerGlobalScope includes GlobalCrypto;
</pre>

you can extend the {{WindowOrWorkerGlobalScope}} [=interface mixin=] using a [=partial interface mixin=]:

<pre highlight="webidl">
    partial interface mixin WindowOrWorkerGlobalScope {
      readonly attribute Crypto crypto;
    };
</pre>


<h3 id="idl-callback-interfaces">Callback interfaces</h3>

A <dfn id="dfn-callback-interface" export>callback interface</dfn> is a [=definition=] matching
<emu-t>callback</emu-t> <emu-t>interface</emu-t> <emu-nt><a href="#prod-InterfaceRest">InterfaceRest</a></emu-nt>.
It can be implemented by any object, as described in [[#idl-objects]].

Note: A [=callback interface=] is not an [=interface=]. The name and syntax are left over from
earlier versions of this standard, where these concepts had more in common.

A [=callback interface=] is a specification of a set of
<dfn export lt="callback interface member">callback interface members</dfn>
(matching <emu-nt><a href="#prod-CallbackInterfaceMembers">CallbackInterfaceMembers</a></emu-nt>).
These are the [=members=] that appear between the braces in the interface declaration.

<pre highlight="webidl" class="syntax">
    callback interface identifier {
      /* interface_members... */
    };
</pre>

Note: See also the similarly named [=callback function=] definition.

[=Callback interfaces=] must define exactly one [=regular operation=].

<div class="advisement">

    Specification authors should not define
    [=callback interfaces=]
    unless required to describe the requirements of existing APIs.
    Instead, a [=callback function=] should be used.

    The definition of {{EventListener}} as a
    [=callback interface=]
    is an example of an existing API that needs to allow
    objects with a
    given property (in this case <code class="idl">handleEvent</code>) to be considered to implement the interface.
    For new APIs, and those for which there are no compatibility concerns,
    using a [=callback function=] will allow
    only a [=function object=] (in the ECMAScript
    language binding).

</div>

[=Callback interfaces=] which declare [=constants=]
must be annotated with an [{{Exposed}}] [=extended attribute=].


<pre class="grammar" id="prod-CallbackRestOrInterface">
    CallbackRestOrInterface :
        CallbackRest
        "interface" identifier "{" CallbackInterfaceMembers "}" ";"
</pre>

<pre class="grammar" id="prod-CallbackInterfaceMembers">
    CallbackInterfaceMembers :
        ExtendedAttributeList CallbackInterfaceMember CallbackInterfaceMembers
        ε
</pre>

<pre class="grammar" id="prod-CallbackInterfaceMember">
    CallbackInterfaceMember :
        Const
        RegularOperation
</pre>


<h3 id="idl-members">Members</h3>

[=Interfaces=], [=interface mixins=], and [=namespaces=] are specifications of a set of
<dfn id="dfn-member" export lt="members">members</dfn> (respectively matching
<emu-nt><a href="#prod-InterfaceMembers">InterfaceMembers</a></emu-nt>,
<emu-nt><a href="#prod-MixinMembers">MixinMembers</a></emu-nt>, and
<emu-nt><a href="#prod-NamespaceMembers">NamespaceMembers</a></emu-nt>),
which are the [=constants=], [=attributes=], [=operations=], and
other declarations that appear between the braces of their declarations.
[=Attributes=] describe the state that an object
implementing the [=interface=], [=interface mixin=], or [=namespace=] will expose,
and [=operations=] describe the behaviors that can be invoked on the object.
[=Constants=] declare named constant values
that are exposed as a convenience to users of objects in the system.

<div class="note">

    When an [=interface=] [=includes=] an [=interface mixin=], each [=member=]
    of the interface mixin is also considered a member of the interface. In contrast,
    [=interface/inherit|inherited=] interface members are not considered members
    of the interface.

</div>

The algorithm steps for every [=regular operation=], [=regular attribute=] getter, and
[=regular attribute=] setter's defined on an [=interface=] or [=interface mixin=] have access to a
<dfn export>this</dfn> value, which is an IDL value of the [=interface=] type that the member is
declared on or that [=includes=] the [=interface mixin=] the member is declared on.

[=Attribute=] setter's algorithm steps also have access to <dfn export>the given value</dfn>,
which is an IDL value of the type the [=attribute=] is declared as.

[=Interfaces=], [=interface mixins=], [=callback interfaces=] and [=namespaces=] each support a
different set of [=members=],
which are specified in [[#idl-interfaces]], [[#idl-interface-mixins]],
[[#idl-callback-interfaces]], and [[#idl-namespaces]],
and summarized in the following informative table:

<table class="data complex non-normative">
    <thead>
        <tr>
            <th></th>
            <th>[=Interfaces=]</th>
            <th>[=Callback interfaces=]</th>
            <th>[=Interface mixins=]</th>
            <th>[=Namespaces=]</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <th>[=Constants=]</th>
            <td>●</td>
            <td>●</td>
            <td>●</td>
            <td></td>
        </tr>
        <tr>
            <th>[=Regular attributes=]</th>
            <td>●</td>
            <td></td>
            <td>●</td>
            <td>Only [=read only=] attributes</td>
        </tr>
        <tr>
            <th>[=Static attributes=]</th>
            <td>●</td>
            <td></td>
            <td></td>
            <td></td>
        </tr>
        <tr>
            <th>[=Regular Operations=]</th>
            <td>●</td>
            <td>●</td>
            <td>●</td>
            <td>●</td>
        </tr>
        <tr>
            <th>[=Special Operations=]</th>
            <td>●</td>
            <td></td>
            <td>Only [=stringifiers=]</td>
            <td></td>
        </tr>
        <tr>
            <th>[=Static Operations=]</th>
            <td>●</td>
            <td></td>
            <td></td>
            <td></td>
        </tr>
        <tr>
            <th>[=Iterable declarations=]</th>
            <td>●</td>
            <td></td>
            <td></td>
            <td></td>
        </tr>
        <tr>
            <th>[=Asynchronously iterable declarations=]</th>
            <td>●</td>
            <td></td>
            <td></td>
            <td></td>
        </tr>
        <tr>
            <th>[=Maplike declarations=]</th>
            <td>●</td>
            <td></td>
            <td></td>
            <td></td>
        </tr>
        <tr>
            <th>[=Setlike declarations=]</th>
            <td>●</td>
            <td></td>
            <td></td>
            <td></td>
        </tr>
    </tbody>
</table>

<h4 id="idl-constants">Constants</h4>

A <dfn id="dfn-constant" export>constant</dfn> is a declaration (matching
<emu-nt><a href="#prod-Const">Const</a></emu-nt>) used to bind a constant value to a name.
Constants can appear on [=interfaces=] and [=callback interfaces=].

<p class="advisement">
    Constants have in the past primarily been used to define
    named integer codes in the style of an enumeration.  The Web platform
    is moving away from this design pattern in favor of the use of strings.
    Editors who wish to use this feature are strongly advised to discuss this
    by <a href="https://github.com/heycam/webidl/issues/new?title=Intent%20to%20use%20Constants">filing an issue</a>
    before proceeding.
</p>

<pre highlight="webidl" class="syntax">const type constant_identifier = 42;</pre>

The [=identifier=] of a
[=constant=]
must not be the same as the identifier
of another [=interface member=] or [=callback interface member=]
defined on the same [=interface=] or [=callback interface=].
The identifier also must not
be "<code>length</code>", "<code>name</code>" or "<code>prototype</code>".

Note: These three names are the names of properties that are defined on the
[=interface object=] in the ECMAScript language binding.

The type of a constant (matching <emu-nt><a href="#prod-ConstType">ConstType</a></emu-nt>)
must not be any type other than
a [=primitive type=].
If an [=identifier=] is used,
it must reference a [=typedef=]
whose type is a primitive type.

The <emu-nt><a href="#prod-ConstValue">ConstValue</a></emu-nt> part of a
constant declaration gives the value of the constant, which can be
one of the two boolean literal tokens (<emu-t>true</emu-t>
and <emu-t>false</emu-t>), an
<emu-t class="regex"><a href="#prod-integer">integer</a></emu-t> token,
a <emu-t class="regex"><a href="#prod-decimal">decimal</a></emu-t> token,
or one of the three special floating point constant values
(<emu-t>-Infinity</emu-t>, <emu-t>Infinity</emu-t> and <emu-t>NaN</emu-t>).

Note: These values – in addition to strings and the empty sequence – can also be used to specify the
[=dictionary member/default value|default value of a dictionary member=] or [=optional argument/default value|of an optional argument=].  Note that strings, the
empty sequence <emu-t>[]</emu-t>, and the default dictionary <emu-t>{}</emu-t> cannot be used as the value of a
[=constant=].

The value of the boolean literal tokens <emu-t>true</emu-t> and
<emu-t>false</emu-t> are the IDL {{boolean}} values
<code class="idl">true</code> and <code class="idl">false</code>.

<div algorithm="value of integer tokens">

    The value of an <emu-t class="regex"><a href="#prod-integer">integer</a></emu-t> token
    is an integer whose value is determined as follows:

    1.  Let |S| be the sequence of characters matched by the <emu-t class="regex"><a href="#prod-integer">integer</a></emu-t> token.
    1.  Let |sign| be −1 if |S| begins with <span class="char">U+002D HYPHEN-MINUS ("-")</span>, and 1 otherwise.
    1.  Let |base| be the base of the number based on the characters that follow the optional leading <span class="char">U+002D HYPHEN-MINUS ("-")</span> character:
        <dl class="switch">
             :  <span class="char">U+0030 DIGIT ZERO ("0")</span>, <span class="char">U+0058 LATIN CAPITAL LETTER X ("X")</span>
             :  <span class="char">U+0030 DIGIT ZERO ("0")</span>, <span class="char">U+0078 LATIN SMALL LETTER X ("x")</span>
             :: The base is 16.
             :  <span class="char">U+0030 DIGIT ZERO ("0")</span>
             :: The base is 8.
             :  <span class="char">Otherwise</span>
             :: The base is 10.
        </dl>
    1.  Let |number| be the result of interpreting all remaining characters following the optional leading <span class="char">U+002D HYPHEN-MINUS ("-")</span>
        character and any characters indicating the base as an integer specified in base |base|.
    1.  Return |sign| × |number|.
</div>

The type of an <emu-t class="regex"><a href="#prod-integer">integer</a></emu-t> token is the same
as the type of the constant, dictionary member or optional argument it is being used as the value of.
The value of the <emu-t class="regex"><a href="#prod-integer">integer</a></emu-t> token must not
lie outside the valid range of values for its type, as given in
[[#idl-types]].

<div id="decimal-token-value" algorithm="value of decimal tokens">
    The value of a <emu-t class="regex"><a href="#prod-decimal">decimal</a></emu-t> token is
    either an IEEE 754 single-precision floating point number or an IEEE 754
    double-precision floating point number, depending on the type of the
    constant, dictionary member or optional argument it is being used as the value for, determined as follows:

    1.  Let |S| be the sequence of characters matched by the
        <emu-t class="regex"><a href="#prod-decimal">decimal</a></emu-t> token.
    1.  Let |result| be the Mathematical Value that would be obtained if
        |S| were parsed as an ECMAScript <emu-nt>[=NumericLiteral=]</emu-nt>.
    1.  If the <emu-t class="regex"><a href="#prod-decimal">decimal</a></emu-t> token is being
        used as the value for a {{float}} or {{unrestricted float}}, then
        the value of the <emu-t class="regex"><a href="#prod-decimal">decimal</a></emu-t> token
        is the IEEE 754 single-precision floating point number closest to |result|.
    1.  Otherwise, the <emu-t class="regex"><a href="#prod-decimal">decimal</a></emu-t> token is being
        used as the value for a {{double}} or {{unrestricted double}}, and
        the value of the <emu-t class="regex"><a href="#prod-decimal">decimal</a></emu-t> token
        is the IEEE 754 double-precision floating point number closest to |result|. [[!IEEE-754]]
</div>

The value of a constant value specified as
<emu-t>Infinity</emu-t>, <emu-t>-Infinity</emu-t> or <emu-t>NaN</emu-t> is either
an IEEE 754 single-precision floating point number or an IEEE 754
double-precision floating point number, depending on the type of the
constant, dictionary member or optional argument is is being used as the
value for:

<dl class="switch">
     :  Type {{unrestricted float}}, constant value <emu-t>Infinity</emu-t>
     :: The value is the IEEE 754 single-precision positive infinity value.
     :  Type {{unrestricted double}}, constant value <emu-t>Infinity</emu-t>
     :: The value is the IEEE 754 double-precision positive infinity value.
     :  Type {{unrestricted float}}, constant value <emu-t>-Infinity</emu-t>
     :: The value is the IEEE 754 single-precision negative infinity value.
     :  Type {{unrestricted double}}, constant value <emu-t>-Infinity</emu-t>
     :: The value is the IEEE 754 double-precision negative infinity value.
     :  Type {{unrestricted float}}, constant value <emu-t>NaN</emu-t>
     :: The value is the IEEE 754 single-precision NaN value with the bit pattern 0x7fc00000.
     :  Type {{unrestricted double}}, constant value <emu-t>NaN</emu-t>
     :: The value is the IEEE 754 double-precision NaN value with the bit pattern 0x7ff8000000000000.
</dl>

The type of a <emu-t class="regex"><a href="#prod-decimal">decimal</a></emu-t> token is the same
as the type of the constant, dictionary member or optional argument it is being used as the value of.
The value of the <emu-t class="regex"><a href="#prod-decimal">decimal</a></emu-t> token must not
lie outside the valid range of values for its type, as given in [[#idl-types]].
Also, <emu-t>Infinity</emu-t>, <emu-t>-Infinity</emu-t> and <emu-t>NaN</emu-t> must not
be used as the value of a {{float}} or {{double}}.

The value of the <emu-t>null</emu-t> token is the special
<emu-val>null</emu-val> value that is a member of the
[=nullable types=].  The type of
the <emu-t>null</emu-t> token is the same as the
type of the constant, dictionary member or optional argument it is being used as the value of.

If |VT| is the type of the value assigned to a constant, and |DT|
is the type of the constant, dictionary member or optional argument itself, then these types must
be compatible, which is the case if |DT| and |VT| are identical,
or |DT| is a [=nullable type=]
whose [=nullable types/inner type=] is |VT|.

[=Constants=] are not associated with
particular instances of the [=interface=] or [=callback interface=]
on which they appear.  It is language binding specific whether
[=constants=] are exposed on instances.

<div class="note">

    The ECMAScript language binding does however
    allow [=constants=] to be accessed
    through objects implementing the IDL [=interfaces=]
    on which the [=constants=] are declared.
    For example, with the following IDL:

    <pre highlight="webidl">
        [Exposed=Window]
        interface A {
          const short rambaldi = 47;
        };
    </pre>

    the constant value can be accessed in ECMAScript  either as
    <code>A.rambaldi</code> or <code>instanceOfA.rambaldi</code>.

</div>

The following extended attributes are applicable to constants:
[{{Exposed}}],
[{{SecureContext}}].

<pre class="grammar" id="prod-Const">
    Const :
        "const" ConstType identifier "=" ConstValue ";"
</pre>

<pre class="grammar" id="prod-ConstValue">
    ConstValue :
        BooleanLiteral
        FloatLiteral
        integer
</pre>

<pre class="grammar" id="prod-BooleanLiteral">
    BooleanLiteral :
        "true"
        "false"
</pre>

<pre class="grammar" id="prod-FloatLiteral">
    FloatLiteral :
        decimal
        "-Infinity"
        "Infinity"
        "NaN"
</pre>

<pre class="grammar" id="prod-ConstType">
    ConstType :
        PrimitiveType
        identifier
</pre>

<div class="example">

    The following [=IDL fragment=]
    demonstrates how [=constants=]
    of the above types can be defined.

    <pre highlight="webidl">
        [Exposed=Window]
        interface Util {
          const boolean DEBUG = false;
          const octet LF = 10;
          const unsigned long BIT_MASK = 0x0000fc00;
          const double AVOGADRO = 6.022e23;
        };
    </pre>
</div>


<h4 id="idl-attributes">Attributes</h4>

An <dfn id="dfn-attribute" export>attribute</dfn> is an [=interface member=] or [=namespace member=]
(matching
<emu-t>inherit</emu-t> <emu-nt><a href="#prod-AttributeRest">AttributeRest</a></emu-nt>,
<emu-t>static</emu-t> <emu-nt><a href="#prod-ReadOnly">ReadOnly</a></emu-nt> <emu-nt><a href="#prod-AttributeRest">AttributeRest</a></emu-nt>,
<emu-t>stringifier</emu-t> <emu-nt><a href="#prod-ReadOnly">ReadOnly</a></emu-nt> <emu-nt><a href="#prod-AttributeRest">AttributeRest</a></emu-nt>,
<emu-nt><a href="#prod-ReadOnly">ReadOnly</a></emu-nt> <emu-nt><a href="#prod-AttributeRest">AttributeRest</a></emu-nt>,
or <emu-nt><a href="#prod-AttributeRest">AttributeRest</a></emu-nt>)
that is used to declare data fields with a given type and
[=identifier=] whose value can
be retrieved and (in some cases) changed.  There are two kinds of attributes:

1.  [=regular attributes=], which are those
    used to declare that objects implementing the [=interface=]
    will have a data field member with the given [=identifier=]
        <pre highlight="webidl" class="syntax">
        interface interface_identifier {
          attribute type identifier;
        };
    </pre>
1.  [=static attributes=], which are used
    to declare attributes that are not associated with a particular object implementing the interface
        <pre highlight="webidl" class="syntax">
        interface interface_identifier {
          static attribute type identifier;
        };
    </pre>

If an attribute has no <emu-t>static</emu-t> keyword, then it declares a
<dfn id="dfn-regular-attribute" export>regular attribute</dfn>.  Otherwise,
it declares a [=static attribute=]. Note that in addition to being [=interface members=],
[=read only=] [=regular attributes=] can be [=namespace members=] as well.


<div algorithm>
    To <dfn export>get the underlying value</dfn> of an attribute |attr| given a value |target|,
    return the result of performing the actions listed in the description of |attr| that occur on getting,
    or those listed in the description of the inherited attribute,
    if |attr| is declared to inherit its getter, with |target| as <b>[=this=]</b> if it is not null.
</div>

The [=identifier=] of an
[=attribute=]
must not be the same as the identifier
of another [=interface member=]
defined on the same [=interface=].
The identifier of a static attribute must not
be "<code>prototype</code>".

The type of the attribute is given by the type (matching <emu-nt><a href="#prod-Type">Type</a></emu-nt>)
that appears after the <emu-t>attribute</emu-t> keyword.
If the <emu-nt><a href="#prod-Type">Type</a></emu-nt> is an
[=identifier=] or an identifier followed by <emu-t>?</emu-t>,
then the identifier must
identify an [=interface=], [=enumeration=],
[=callback function=], [=callback interface=] or [=typedef=].

The type of the attribute, after resolving typedefs, must not be a
[=nullable type|nullable=] or non-nullable version of any of the following types:

*   a [=sequence type=]
*   a [=dictionary type=]
*   a [=record type=]
*   a [=union type=]
    that has a nullable or non-nullable sequence type, dictionary,
    or record
    as one of its [=flattened member types=]

The attribute is <dfn id="dfn-read-only" export>read only</dfn> if the
<emu-t>readonly</emu-t> keyword is used before the <emu-t>attribute</emu-t> keyword.
An object that implements the interface on which a read only attribute
is defined will not allow assignment to that attribute.  It is language
binding specific whether assignment is simply disallowed by the language,
ignored or an exception is thrown.

    <pre highlight="webidl" class="syntax">
    interface interface_identifier {
      readonly attribute type identifier;
    };
</pre>

Attributes whose type is a [=promise type=] must be [=read only=]. Additionally, they cannot have
any of the [=extended attributes=] [{{LenientSetter}}], [{{PutForwards}}], [{{Replaceable}}], or
[{{SameObject}}].

A [=regular attribute=]
that is not [=read only=]
can be declared to <dfn id="dfn-inherit-getter" export>inherit its getter</dfn>
from an ancestor interface.  This can be used to make a read only attribute
in an ancestor interface be writable on a derived interface.  An attribute
[=inherit its getter|inherits its getter=] if
its declaration includes <emu-t>inherit</emu-t> in the declaration.
The read only attribute from which the attribute inherits its getter
is the attribute with the same identifier on the closest ancestor interface
of the one on which the inheriting attribute is defined.  The attribute
whose getter is being inherited must be
of the same type as the inheriting attribute.

Note: The grammar ensures that <emu-t>inherit</emu-t> does not appear on a [=read only=] attribute
or a [=static attribute=].

<pre highlight="webidl" class="syntax">
    [Exposed=Window]
    interface Ancestor {
      readonly attribute TheType theIdentifier;
    };

    [Exposed=Window]
    interface Derived : Ancestor {
      inherit attribute TheType theIdentifier;
    };
</pre>

When the <emu-t>stringifier</emu-t> keyword is used
in a [=regular attribute=]
declaration, it indicates that objects implementing the
interface will be stringified to the value of the attribute.  See
[[#idl-stringifiers]] for details.

<pre highlight="webidl" class="syntax">
    interface interface_identifier {
      stringifier attribute DOMString identifier;
    };
</pre>

The following [=extended attributes=]
are applicable to regular and static attributes:
[{{Exposed}}],
[{{SameObject}}],
[{{SecureContext}}].

The following [=extended attributes=]
are applicable only to regular attributes:
[{{LenientSetter}}],
[{{LenientThis}}],
[{{PutForwards}}],
[{{Replaceable}}],
[{{Unforgeable}}].

<pre class="grammar" id="prod-ReadOnlyMember">
    ReadOnlyMember :
        "readonly" ReadOnlyMemberRest
</pre>

<pre class="grammar" id="prod-ReadOnlyMemberRest">
    ReadOnlyMemberRest :
        AttributeRest
        MaplikeRest
        SetlikeRest
</pre>

<pre class="grammar" id="prod-ReadWriteAttribute">
    ReadWriteAttribute :
        "inherit" AttributeRest
        AttributeRest
</pre>

<pre class="grammar" id="prod-AttributeRest">
    AttributeRest :
        "attribute" TypeWithExtendedAttributes AttributeName ";"
</pre>

<pre class="grammar" id="prod-AttributeName">
    AttributeName :
        AttributeNameKeyword
        identifier
</pre>

<pre class="grammar" id="prod-AttributeNameKeyword">
    AttributeNameKeyword :
        "async"
        "required"
</pre>

<pre class="grammar" id="prod-ReadOnly">
    ReadOnly :
        "readonly"
        ε
</pre>

<div class="example">

    The following [=IDL fragment=]
    demonstrates how [=attributes=]
    can be declared on an [=interface=]:

    <pre highlight="webidl">
        [Exposed=Window]
        interface Animal {

          // A simple attribute that can be set to any string value.
          readonly attribute DOMString name;

          // An attribute whose value can be assigned to.
          attribute unsigned short age;
        };

        [Exposed=Window]
        interface Person : Animal {

          // An attribute whose getter behavior is inherited from Animal, and need not be
          // specified in the description of Person.
          inherit attribute DOMString name;
        };
    </pre>
</div>


<h4 id="idl-operations">Operations</h4>

An <dfn id="dfn-operation" export>operation</dfn> is an [=interface member=], [=callback interface
member=] or [=namespace member=]
(matching <emu-t>static</emu-t> <emu-nt><a href="#prod-RegularOperation">RegularOperation</a></emu-nt>,
<emu-t>stringifier</emu-t> <emu-nt><a href="#prod-RegularOperation">RegularOperation</a></emu-nt>,
<emu-nt><a href="#prod-RegularOperation">RegularOperation</a></emu-nt> or
<emu-nt><a href="#prod-SpecialOperation">SpecialOperation</a></emu-nt>)
that defines a behavior that can be invoked on objects implementing the interface.
There are three kinds of operation:

1.  [=regular operations=], which
    are those used to declare that objects implementing the
    [=interface=] will have a method with
    the given [=identifier=]
    <pre highlight="webidl" class="syntax">
        interface interface_identifier {
          return_type identifier(/* arguments... */);
        };
    </pre>
1.  [=special operations=],
    which are used to declare special behavior on objects
    implementing the interface, such as object indexing and stringification
    <pre highlight="webidl" class="syntax">
        interface interface_identifier {
          /* special_keyword */ return_type identifier(/* arguments... */);
          /* special_keyword */ return_type (/* arguments... */);
        };
    </pre>
1.  [=static operations=],
    which are used to declare operations that are not associated with
    a particular object implementing the interface
    <pre highlight="webidl" class="syntax">
        interface interface_identifier {
          static return_type identifier(/* arguments... */);
        };
    </pre>

If an operation has an identifier but no <emu-t>static</emu-t>
keyword, then it declares a <dfn id="dfn-regular-operation" export>regular operation</dfn>.
If the operation has a
[=special keyword=]
used in its declaration (that is, any keyword matching
<emu-nt><a href="#prod-Special">Special</a></emu-nt>, or
the <emu-t>stringifier</emu-t> keyword),
then it declares a special operation.  A single operation can declare
both a regular operation and a special operation;
see [[#idl-special-operations]] for details on special operations.
Note that in addition to being [=interface members=],
regular operations can also be [=callback interface members=] and [=namespace members=].

If an operation has no identifier,
then it must be declared to be a special operation
using one of the special keywords.

The identifier of a [=regular operation=] or [=static operation=]
must not be the same as the identifier
of a [=constant=] or [=attribute=]
defined on the same [=interface=], [=callback interface=] or [=namespace=].
The identifier of a static operation must not be "<code>prototype</code>".

Note: The identifier can be the same
as that of another operation on the interface, however.
This is how operation overloading is specified.

The [=identifier=] of a [=static operation=]
also must not be the same as the identifier
of a [=regular operation=]
defined on the same [=interface=].

The <dfn id="dfn-return-type" export>return type</dfn> of the operation is given
by the type (matching <emu-nt><a href="#prod-ReturnType">ReturnType</a></emu-nt>)
that appears before the operation’s optional [=identifier=].
A return type of {{void}} indicates that the operation returns no value.
If the return type is an
[=identifier=] followed by <emu-t>?</emu-t>,
then the identifier must
identify an [=interface=], [=dictionary=], [=enumeration=],
[=callback function=], [=callback interface=] or [=typedef=].

An operation’s arguments (matching <emu-nt><a href="#prod-ArgumentList">ArgumentList</a></emu-nt>)
are given between the parentheses in the declaration.  Each individual argument is specified
as a type (matching <emu-nt><a href="#prod-Type">Type</a></emu-nt>) followed by an [=identifier=]
(matching <emu-nt><a href="#prod-ArgumentName">ArgumentName</a></emu-nt>).

Note: For expressiveness, the identifier of an operation argument can also be specified
as one of the keywords matching the <emu-nt><a href="#prod-ArgumentNameKeyword">ArgumentNameKeyword</a></emu-nt>
symbol without needing to escape it.

If the <emu-nt><a href="#prod-Type">Type</a></emu-nt> of an operation argument is an identifier
followed by <emu-t>?</emu-t>,
then the identifier must identify an [=interface=],
[=enumeration=], [=callback function=], [=callback interface=],
or [=typedef=].
If the operation argument type is an [=identifier=]
not followed by <emu-t>?</emu-t>, then the identifier must
identify any one of those definitions or a [=dictionary=].

If the operation argument type, after resolving typedefs,
is a [=nullable type=],
its [=nullable types/inner type=] must not be a [=dictionary type=].

<pre highlight="webidl" class="syntax">
    interface interface_identifier {
      return_type identifier(type identifier, type identifier /* , ... */);
    };
</pre>

The identifier of each argument must not be the same
as the identifier of another argument in the same operation declaration.

Each argument can be preceded by a list of
[=extended attributes=] (matching
<emu-nt><a href="#prod-ExtendedAttributeList">ExtendedAttributeList</a></emu-nt>),
which can control how a value passed as the argument will be handled in
language bindings.

<pre highlight="webidl" class="syntax">
    interface interface_identifier {
      return_type identifier([<mark>extended_attributes</mark>] type identifier, [<mark>extended_attributes</mark>] type identifier /* , ... */);
    };
</pre>

<div class="example">

    The following [=IDL fragment=]
    demonstrates how [=regular operations=]
    can be declared on an [=interface=]:

    <pre highlight="webidl">
        [Exposed=Window]
        interface Dimensions {
          attribute unsigned long width;
          attribute unsigned long height;
        };

        [Exposed=Window]
        interface Button {

          // An operation that takes no arguments and returns a boolean.
          boolean isMouseOver();

          // Overloaded operations.
          void setDimensions(Dimensions size);
          void setDimensions(unsigned long width, unsigned long height);
        };
    </pre>
</div>

An operation or [=constructor operation=] is considered to be
<dfn id="dfn-variadic" export>variadic</dfn>
if the final argument uses the <emu-t>...</emu-t> token just
after the argument type.  Declaring an operation to be variadic indicates that
the operation can be invoked with any number of arguments after that final argument.
Those extra implied formal arguments are of the same type as the final explicit
argument in the operation declaration.  The final argument can also be omitted
when invoking the operation.  An argument must not
be declared with the <emu-t>...</emu-t> token unless it
is the final argument in the operation’s argument list.

<pre highlight="webidl" class="syntax">
    interface interface_identifier {
      return_type identifier(type<mark>...</mark> identifier);
      return_type identifier(type identifier, type<mark>...</mark> identifier);
    };
</pre>

[=Extended attributes=]
that [=takes an argument list|take an argument list=]
([{{NamedConstructor}}], of those
defined in this specification) and [=callback functions=]
are also considered to be [=variadic=]
when the <emu-t>...</emu-t> token is used in their argument lists.

<div class="example">

    The following [=IDL fragment=] defines an interface that has
    two variadic operations:

    <pre highlight="webidl">
        [Exposed=Window]
        interface IntegerSet {
          readonly attribute unsigned long cardinality;

          void union(long... ints);
          void intersection(long... ints);
        };
    </pre>

    In the ECMAScript binding, variadic operations are implemented by
    functions that can accept the subsequent arguments:

    <pre highlight="js">
        var s = getIntegerSet();  // Obtain an instance of IntegerSet.

        s.union();                // Passing no arguments corresponding to 'ints'.
        s.union(1, 4, 7);         // Passing three arguments corresponding to 'ints'.
    </pre>

    A binding for a language that does not support variadic functions
    might specify that an explicit array or list of integers be passed
    to such an operation.

</div>

An argument is considered to be an <dfn id="dfn-optional-argument" export>optional argument</dfn>
if it is declared with the <emu-t>optional</emu-t> keyword.
The final argument of a [=variadic=] operation
is also considered to be an optional argument. Declaring an argument
to be optional indicates that the argument value can be omitted
when the operation is invoked.  The final argument in an
operation must not explicitly be declared to be
optional if the operation is [=variadic=].

<pre highlight="webidl" class="syntax">
    interface interface_identifier {
      return_type identifier(type identifier, optional type identifier);
    };
</pre>

Optional arguments can also have a <dfn id="dfn-optional-argument-default-value" for="optional argument" export>default value</dfn>
specified.  If the argument’s identifier is followed by a <span class="char">U+003D EQUALS SIGN ("=")</span>
and a value (matching <emu-nt><a href="#prod-DefaultValue">DefaultValue</a></emu-nt>),
then that gives the optional argument its [=optional argument/default value=].
The implicitly optional final argument of a [=variadic=]
operation must not have a default value specified.
The default value is the value to be assumed when the operation is called with the
corresponding argument omitted.

<pre highlight="webidl" class="syntax">
    interface interface_identifier {
      return_type identifier(type identifier, optional type identifier = "value");
    };
</pre>

<p class="advisement">
    It is strongly suggested not to use a [=optional argument/default value=]
    of <emu-val>true</emu-val> for {{boolean}}-typed arguments,
    as this can be confusing for authors who might otherwise expect the default
    conversion of <emu-val>undefined</emu-val> to be used (i.e., <emu-val>false</emu-val>).
</p>

If the type of an argument is a [=dictionary type=] or a [=union type=] that has
a [=dictionary type=] as one
of its [=flattened member types=], and that dictionary type and its ancestors have no
[=required dictionary member|required members=], and the argument is either the final argument or is
followed only by [=optional arguments=], then the argument must be specified as
optional and have a default value provided.

<div class="note">

    This is to encourage API designs that do not require authors to pass an
    empty dictionary value when they wish only to use the dictionary’s
    default values.

    Usually the default value provided will be <emu-t>{}</emu-t>, but in the
    case of a [=union type=] that has a dictionary type as one of its
    [=flattened member types=] a default value could be provided that
    initializes some other member of the union.
</div>

When a boolean literal token (<emu-t>true</emu-t> or <emu-t>false</emu-t>),
the <emu-t>null</emu-t> token,
an <emu-t class="regex"><a href="#prod-integer">integer</a></emu-t> token, a
<emu-t class="regex"><a href="#prod-decimal">decimal</a></emu-t> token or one of
the three special floating point literal values (<emu-t>Infinity</emu-t>,
<emu-t>-Infinity</emu-t> or <emu-t>NaN</emu-t>) is used as the
[=optional argument/default value=],
it is interpreted in the same way as for a [=constant=].

<div id="string-literal" algorithm="value of string literal tokens">
    Optional argument default values can also be specified using a
    <emu-t class="regex"><a href="#prod-string">string</a></emu-t>
    token, whose <dfn lt="value of string literal tokens">value</dfn> is a
    [=string type=] determined as follows:

    1.  Let |S| be the sequence of [=Unicode scalar values=] matched by
        the <emu-t class="regex"><a href="#prod-string">string</a></emu-t> token
        with its leading and trailing <span class="char">U+0022 QUOTATION MARK ('"')</span> characters removed.
    1.  Depending on the type of the argument:
        <dl class="switch">
             :  {{DOMString}}
             :  an [=enumeration=] type
             :: The value of the <emu-t class="regex"><a href="#prod-string">string</a></emu-t> token
                is the sequence of 16 bit unsigned integer code units
                (hereafter referred to just as <dfn id="dfn-code-unit">code units</dfn>)
                corresponding to the UTF-16 encoding of |S|.
             :  {{ByteString}}
             :: The value of the <emu-t class="regex"><a href="#prod-string">string</a></emu-t> token
                is the sequence of 8 bit unsigned integer code units
                corresponding to the UTF-8 encoding of |S|.
             :  {{USVString}}
             :: The value of the <emu-t class="regex"><a href="#prod-string">string</a></emu-t> token is |S|.
        </dl>
</div>

If the type of the [=optional argument=]
is an [=enumeration=], then its
[=optional argument/default value=] if specified must
be one of the [=enumeration values|enumeration’s values=].

Optional argument default values can also be specified using the
two token value <emu-t>[]</emu-t>, which represents an empty sequence
value.  The type of this value is the same as the type of the optional
argument it is being used as the default value of.  That type
must be a [=sequence type=], a [=nullable type=] whose [=nullable types/inner type=] is a
[=sequence type=] or a [=union type=] or [=nullable type|nullable=] union type
that has a [=sequence type=] in its [=flattened member types=].

Optional argument default values can also be specified using the two token value
<emu-t>{}</emu-t>, which represents a default-initialized (as if from ES
<emu-t>null</emu-t> or an object with no properties) dictionary value.  The type
of this value is the same as the type of the optional argument it is being used
as the default value of.  That type must be a [=dictionary type=], or a [=union
type=] that has a [=dictionary type=] in its [=flattened member types=].

<div class="example">

    The following [=IDL fragment=]
    defines an [=interface=]
    with a single [=operation=]
    that can be invoked with two different argument list lengths:

    <pre highlight="webidl">
        [Exposed=Window]
        interface ColorCreator {
          object createColor(double v1, double v2, double v3, optional double alpha);
        };
    </pre>

    It is equivalent to an [=interface=]
    that has two [=overloaded=]
    [=operations=]:

    <pre highlight="webidl">
        [Exposed=Window]
        interface ColorCreator {
          object createColor(double v1, double v2, double v3);
          object createColor(double v1, double v2, double v3, double alpha);
        };
    </pre>
</div>

<div class="example">

    The following [=IDL fragment=]
    defines an [=interface=]
    with an operation that takes a dictionary argument:

    <pre highlight="webidl">
        dictionary LookupOptions {
          boolean caseSensitive = false;
        };

        [Exposed=Window]
        interface AddressBook {
          boolean hasAddressForName(USVString name, optional LookupOptions options = {});
        };
    </pre>

    If <code>hasAddressForName</code> is called with only one argument, the
    second argument will be a default-initialized <code>LookupOptions</code>
    dictionary, which will cause <code>caseSensitive</code> to be set to
    <emu-t>false</emu-t>.
</div>

The following extended attributes are applicable to operations:
[{{Default}}],
[{{Exposed}}],
[{{NewObject}}],
[{{SecureContext}}],
[{{Unforgeable}}].

<pre class="grammar" id="prod-DefaultValue">
    DefaultValue :
        ConstValue
        string
        "[" "]"
        "{" "}"
        "null"
</pre>

<pre class="grammar" id="prod-Operation">
    Operation :
        RegularOperation
        SpecialOperation
</pre>

<pre class="grammar" id="prod-RegularOperation">
    RegularOperation :
        ReturnType OperationRest
</pre>

<pre class="grammar" id="prod-SpecialOperation">
    SpecialOperation :
        Special RegularOperation
</pre>

<pre class="grammar" id="prod-Special">
    Special :
        "getter"
        "setter"
        "deleter"
</pre>

<pre class="grammar" id="prod-OperationRest">
    OperationRest :
        OptionalOperationName "(" ArgumentList ")" ";"
</pre>

<pre class="grammar" id="prod-OptionalOperationName">
    OptionalOperationName :
        OperationName
        ε
</pre>

<pre class="grammar" id="prod-OperationName">
    OperationName :
        OperationNameKeyword
        identifier
</pre>

<pre class="grammar" id="prod-OperationNameKeyword">
    OperationNameKeyword :
        "includes"
</pre>

<pre class="grammar" id="prod-ArgumentList">
    ArgumentList :
        Argument Arguments
        ε
</pre>

<pre class="grammar" id="prod-Arguments">
    Arguments :
        "," Argument Arguments
        ε
</pre>

<pre class="grammar" id="prod-Argument">
    Argument :
        ExtendedAttributeList ArgumentRest
</pre>

<pre class="grammar" id="prod-ArgumentRest">
    ArgumentRest :
        "optional" TypeWithExtendedAttributes ArgumentName Default
        Type Ellipsis ArgumentName
</pre>

<pre class="grammar" id="prod-ArgumentName">
    ArgumentName :
        ArgumentNameKeyword
        identifier
</pre>

<pre class="grammar" id="prod-Ellipsis">
    Ellipsis :
        "..."
        ε
</pre>

<div data-fill-with="grammar-ArgumentNameKeyword"></div>

<pre class="grammar" id="prod-ReturnType">
    ReturnType :
        Type
        "void"
</pre>

<h5 id="idl-tojson-operation">toJSON</h5>

By declaring a <code>toJSON</code> [=regular operation=],
an [=interface=] specifies how to convert the objects that implement it to [=JSON types=].

The <code>toJSON</code> [=regular operation=] is reserved for this usage.
It must take zero arguments and return a [=JSON type=].

The <dfn id="dfn-json-types" export lt="JSON type">JSON types</dfn> are:

*   [=numeric types=],
*   {{boolean}},
*   [=string types=],
*   [=nullable types=] whose [=nullable types/inner type=] is a [=JSON type=],
*   [=annotated types=] whose [=annotated types/inner type=] is a [=JSON type=],
*   [=union types=] whose [=member types=] are [=JSON types=],
*   [=typedefs=] whose [=type being given a new name=] is a [=JSON type=],
*   [=sequence types=] whose parameterized type is a [=JSON type=],
*   [=frozen array types=] whose parameterized type is a [=JSON type=],
*   [=dictionary types=] where the types of all [=dictionary members|members=] declared on the dictionary and all its [=inherited dictionaries=] are [=JSON types=],
*   [=records=] where all of their [=map/values=] are [=JSON types=],
*   {{object}},
*   [=interface types=] that have a <code>toJSON</code> operation declared on themselves or
    one of their [=inherited interfaces=].

How the <code>toJSON</code> [=regular operation=]
is made available on an object in a language binding,
and how exactly the [=JSON types=] are converted into a JSON string,
is language binding specific.

Note: In the ECMAScript language binding,
this is done by exposing a <code>toJSON</code> method
which returns the [=JSON type=]
converted into an ECMAScript value
that can be turned into a JSON string
by the {{JSON.stringify()}} function.
Additionally, in the ECMAScript language binding,
the <code>toJSON</code> operation can take a [{{Default}}] [=extended attribute=],
in which case the [=default toJSON operation=] is exposed instead.

<div class="example" id="tojson-example">

    The following [=IDL fragment=] defines an interface <code class="idl">Transaction</code>
    that has a <code>toJSON</code> method defined in prose:

    <pre highlight="webidl">
        [Exposed=Window]
        interface Transaction {
          readonly attribute DOMString from;
          readonly attribute DOMString to;
          readonly attribute double amount;
          readonly attribute DOMString description;
          readonly attribute unsigned long number;
          TransactionJSON toJSON();
        };

        dictionary TransactionJSON {
          Account from;
          Account to;
          double amount;
          DOMString description;
        };
    </pre>

    The <code>toJSON</code> [=regular operation=] of <code class="idl">Transaction</code> [=interface=]
    could be defined as follows:


    <div algorithm="example tojson">

        To invoke the <code>toJSON()</code> operation of the <code class="idl">Transaction</code>
        interface, run the following steps:

        1.  Let |json| be a new <code class="idl">TransactionJSON</code> dictionary.
        1.  [=list/For each=] attribute [=identifier=] |attr| in « "from", "to", "amount", "description" »:
            1.  Let |value| be result of [=get the underlying value|getting the underlying value=]
                of the [=attribute=] identified by |attr|,
                given <b>this</b>.
            1.  Set |json|[|attr|] to |value|.
        1.  Return |json|.
    </div>

    In the ECMAScript language binding, there would exist a <code>toJSON()</code> method on
    <code class="idl">Transaction</code> objects:

    <pre highlight="js">
        // Get an instance of Transaction.
        var txn = getTransaction();

        // Evaluates to an object like this:
        // {
        //   from: "Bob",
        //   to: "Alice",
        //   amount: 50,
        //   description: "books"
        // }
        txn.toJSON();

        // Evaluates to a string like this:
        // '{"from":"Bob","to":"Alice","amount":50,"description":"books"}'
        JSON.stringify(txn);
    </pre>
</div>


<h4 id=idl-constructors oldids="Constructor" dfn>Constructor operations</h4>

If an [=interface=] has a [=constructor operation=] member (matching
<emu-nt><a href="#prod-Constructor">Constructor</a></emu-nt>), it indicates that it is possible to
create objects that [=implement=] the [=interface=] using a [=constructor=].

Multiple [=constructor operations=] may appear on a given [=interface=].
For each [=constructor operation=] on the [=interface=], there will be a way to attempt to
construct an instance by passing the specified arguments.

The prose definition of a [=constructor operation=] must either initialize the value passed as
<b>[=this=]</b>, or throw an exception.

See [[#interface-object]] for details on how a [=constructor operation=] is to be implemented.

<div class="example">

    The following IDL defines two interfaces. The second has [=constructor operations=], while the
    first does not.

    <pre highlight="webidl">
        [Exposed=Window]
        interface NodeList {
          Node item(unsigned long index);
          readonly attribute unsigned long length;
        };

        [Exposed=Window]
        interface Circle {
          constructor();
          constructor(double radius);
          attribute double r;
          attribute double cx;
          attribute double cy;
          readonly attribute double circumference;
        };
    </pre>

    An ECMAScript implementation supporting these interfaces would implement a \[[Construct]]
    internal method on the <code class="idl">Circle</code> interface object which would return a
    new object that [=implements=] the interface.
    It would take either zero or one argument.

    Issue(heycam/webidl#698): It is unclear whether the <code class="idl">NodeList</code> interface
    object would implement a \[[Construct]] internal method. In any case, trying to use it as a
    constructor will cause a {{TypeError}} to be thrown.

    <pre highlight="js">
        var x = new Circle();      // This uses the zero-argument constructor to create a
                                   // reference to a platform object that implements the
                                   // Circle interface.

        var y = new Circle(1.25);  // This also creates a Circle object, this time using
                                   // the one-argument constructor.

        var z = new NodeList();    // This would throw a TypeError, since no
                                   // constructor is declared.
    </pre>
</div>



<pre class="grammar" id="prod-Constructor">
    Constructor :
        "constructor" "(" ArgumentList ")" ";"
</pre>

<div data-fill-with="grammar-ArgumentList"></div>
<div data-fill-with="grammar-Arguments"></div>
<div data-fill-with="grammar-Argument"></div>
<div data-fill-with="grammar-ArgumentRest"></div>
<div data-fill-with="grammar-ArgumentName"></div>
<div data-fill-with="grammar-Ellipsis"></div>
<div data-fill-with="grammar-ArgumentNameKeyword"></div>


<h4 id="idl-special-operations">Special operations</h4>

A <dfn id="dfn-special-operation" export>special operation</dfn> is a
declaration of a certain kind of special behavior on objects implementing
the interface on which the special operation declarations appear.
Special operations are declared by using a
<dfn id="dfn-special-keyword" export>special keyword</dfn>
in an operation declaration.

There are four kinds of special operations. The table below indicates
for a given kind of special operation what special keyword
is used to declare it and what the purpose of the special operation is:

<table class="vert data">
    <tr>
        <th>Special operation</th>
        <th>Keyword</th>
        <th>Purpose</th>
    </tr>
    <tr>
        <td><dfn id="dfn-getter" export lt="getter">Getters</dfn></td>
        <td><emu-t>getter</emu-t></td>
        <td>Defines behavior for when an object is indexed for property retrieval.</td>
    </tr>
    <tr>
        <td><dfn id="dfn-setter" export lt="setter">Setters</dfn></td>
        <td><emu-t>setter</emu-t></td>
        <td>Defines behavior for when an object is indexed for property
        assignment or creation.</td>
    </tr>
    <tr>
        <td><dfn id="dfn-deleter" export lt="deleter">Deleters</dfn></td>
        <td><emu-t>deleter</emu-t></td>
        <td>Defines behavior for when an object is indexed for property deletion.</td>
    </tr>
    <tr>
        <td><dfn id="dfn-stringifier" export lt="stringifier">Stringifiers</dfn></td>
        <td><emu-t>stringifier</emu-t></td>
        <td>Defines how an object is converted into a {{DOMString}}.</td>
    </tr>
</table>

Not all language bindings support all of the four kinds of special
object behavior.  When special operations are declared using
operations with no identifier, then in language bindings that do
not support the particular kind of special operations there simply
will not be such functionality.

<div class="example">

    The following IDL fragment defines an interface with a getter and a setter:

    <pre highlight="webidl">
        [Exposed=Window]
        interface Dictionary {
          readonly attribute unsigned long propertyCount;

          getter double (DOMString propertyName);
          setter void (DOMString propertyName, double propertyValue);
        };
    </pre>

    In language bindings that do not support property getters and setters,
    objects implementing [=Dictionary=] will not
    have that special behavior.

</div>

Defining a special operation  with an [=identifier=]
is equivalent to separating the special operation out into its own
declaration without an identifier.  This approach is allowed to
simplify prose descriptions of an interface’s operations.

<div class="example">

    The following two interfaces are equivalent:

    <pre highlight="webidl">
        [Exposed=Window]
        interface Dictionary {
          readonly attribute unsigned long propertyCount;

          getter double getProperty(DOMString propertyName);
          setter void setProperty(DOMString propertyName, double propertyValue);
        };
    </pre>
    <pre highlight="webidl">
        [Exposed=Window]
        interface Dictionary {
          readonly attribute unsigned long propertyCount;

          double getProperty(DOMString propertyName);
          void setProperty(DOMString propertyName, double propertyValue);

          getter double (DOMString propertyName);
          setter void (DOMString propertyName, double propertyValue);
        };
    </pre>
</div>

A given [=special keyword=] must not
appear twice on an operation.

Getters and setters come in two varieties: ones that
take a {{DOMString}} as a property name,
known as
<dfn id="dfn-named-property-getter" export lt="named property getter">named property getters</dfn> and
<dfn id="dfn-named-property-setter" export lt="named property setter">named property setters</dfn>,
and ones that take an {{unsigned long}}
as a property index, known as
<dfn id="dfn-indexed-property-getter" export lt="indexed property getter">indexed property getters</dfn> and
<dfn id="dfn-indexed-property-setter" export lt="indexed property setter">indexed property setters</dfn>.
There is only one variety of deleter:
<dfn id="dfn-named-property-deleter" export lt="named property deleter">named property deleters</dfn>.
See [[#idl-indexed-properties]]
and [[#idl-named-properties]]
for details.

On a given [=interface=],
there must exist at most one
stringifier, at most one
[=named property deleter=],
and at most one of each variety of getter and setter.

If an interface has a setter of a given variety,
then it must also have a getter of that
variety.  If it has a [=named property deleter=],
then it must also have a
[=named property getter=].

Special operations declared using operations must not
be [=variadic=] nor have any
[=optional arguments=].

If an object implements more than one [=interface=]
that defines a given special operation, then it is undefined which (if any)
special operation is invoked for that operation.


<h5 id="idl-stringifiers">Stringifiers</h5>

When an [=interface=] has a
[=stringifier=], it indicates that objects that implement
the interface have a non-default conversion to a string.  As mentioned above,
stringifiers can be specified using an [=operation=]
declared with the <emu-t>stringifier</emu-t> keyword.

<pre highlight="webidl" class="syntax">
    interface interface_identifier {
      stringifier DOMString identifier();
      stringifier DOMString ();
    };
</pre>

If an operation used to declare a stringifier does not have an
[=identifier=], then prose
accompanying the interface must define
the <dfn id="dfn-stringification-behavior" export>stringification behavior</dfn>
of the interface.  If the operation does have an identifier,
then the object is converted to a string by invoking the
operation to obtain the string.

Stringifiers declared with operations must
be declared to take zero arguments and return a {{DOMString}}.

As a shorthand, if the <emu-t>stringifier</emu-t> keyword
is declared using an operation with no identifier, then the
operation’s [=return type=] and
argument list can be omitted.

<pre highlight="webidl" class="syntax">
    interface interface_identifier {
      stringifier;
    };
</pre>

<div class="example">

    The following two interfaces are equivalent:

    <pre highlight="webidl">
        [Exposed=Window]
        interface A {
          stringifier DOMString ();
        };
    </pre>
    <pre highlight="webidl">
        [Exposed=Window]
        interface A {
          stringifier;
        };
    </pre>
</div>

The <emu-t>stringifier</emu-t> keyword
can also be placed on an [=attribute=].
In this case, the string to convert the object to is the
value of the attribute.  The <emu-t>stringifier</emu-t> keyword
must not be placed on an attribute unless
it is declared to be of type {{DOMString}} or {{USVString}}.
It also must not be placed on
a [=static attribute=].

<pre highlight="webidl" class="syntax">
    interface interface_identifier {
      stringifier attribute DOMString identifier;
    };
</pre>

<pre class="grammar" id="prod-Stringifier">
    Stringifier :
        "stringifier" StringifierRest
</pre>

<pre class="grammar" id="prod-StringifierRest">
    StringifierRest :
        ReadOnly AttributeRest
        RegularOperation
        ";"
</pre>

<div class="example">

    The following [=IDL fragment=]
    defines an interface that will stringify to the value of its
    <code class="idl">name</code> attribute:

    <pre highlight="webidl">
        [Exposed=Window]
        interface Student {
          constructor();
          attribute unsigned long id;
          stringifier attribute DOMString name;
        };
    </pre>

    In the ECMAScript binding, using a <code class="idl">Student</code>
    object in a context where a string is expected will result in the
    value of the object’s <code class="idl">name</code> property being
    used:

    <pre highlight="js">
        var s = new Student();
        s.id = 12345678;
        s.name = '周杰倫';

        var greeting = 'Hello, ' + s + '!';  // Now greeting == 'Hello, 周杰倫!'.
    </pre>

    The following [=IDL fragment=]
    defines an interface that has custom stringification behavior that is
    not specified in the IDL itself.

    <pre highlight="webidl">
        [Exposed=Window]
        interface Student {
          constructor();
          attribute unsigned long id;
          attribute DOMString? familyName;
          attribute DOMString givenName;

          stringifier DOMString ();
        };
    </pre>

    Thus, prose is required to explain the stringification behavior, such
    as the following paragraph:

    <blockquote>

        Objects that implement the <code class="idl">Student</code>
        interface must stringify as follows.  If the value of the
        <code class="idl">familyName</code> attribute is
        <emu-val>null</emu-val>, the stringification of the
        object is the value of the <code class="idl">givenName</code>
        attribute.  Otherwise, if the value of the
        <code class="idl">familyName</code> attribute is not <emu-val>null</emu-val>,
        the stringification of the object is the concatenation of the
        value of the <code class="idl">givenName</code> attribute,
        a single space character, and the value of
        the <code class="idl">familyName</code> attribute.

    </blockquote>

    An ECMAScript implementation of the IDL would behave as follows:

    <pre highlight="js">
        var s = new Student();
        s.id = 12345679;
        s.familyName = 'Smithee';
        s.givenName = 'Alan';

        var greeting = 'Hi ' + s;  // Now greeting == 'Hi Alan Smithee'.
    </pre>
</div>


<h5 id="idl-indexed-properties" dfn export>Indexed properties</h5>

An [=interface=] that defines an [=indexed property getter=]
is said to <dfn id="dfn-support-indexed-properties" export>support indexed properties</dfn>.
By extension, a [=platform object=]
is said to [=support indexed properties=] if
it implements an [=interface=] that itself does.

If an interface [=support indexed properties|supports indexed properties=],
then the interface definition must be accompanied by
a description of what indices the object can be indexed with at
any given time. These indices are called the <dfn id="dfn-supported-property-indices" export>supported property indices</dfn>.

Interfaces that [=support indexed properties=] must define
an [=integer types|integer-typed=] [=attribute=] named "<code>length</code>".

Indexed property getters must
be declared to take a single {{unsigned long}} argument.
Indexed property setters must
be declared to take two arguments, where the first is an {{unsigned long}}.

<pre highlight="webidl" class="syntax">
    interface interface_identifier {
      getter type identifier(unsigned long identifier);
      setter type identifier(unsigned long identifier, type identifier);

      getter type (unsigned long identifier);
      setter type (unsigned long identifier, type identifier);
    };
</pre>

The following requirements apply to the definitions of indexed property getters and setters:

*   If an [=indexed property getter=] was specified using an [=operation=]
    with an [=identifier=],
    then the value returned when indexing the object with a given [=supported property indices|supported property index=]
    is the value that would be returned by invoking the operation, passing
    the index as its only argument.  If the operation used to declare the indexed property getter
    did not have an identifier, then the interface definition must be accompanied
    by a description of how to <dfn id="dfn-determine-the-value-of-an-indexed-property" export>determine the value of an indexed property</dfn>
    for a given index.
*   If an [=indexed property setter=] was specified using an operation
    with an identifier,
    then the behavior that occurs when indexing the object for property assignment with a given supported property index and value
    is the same as if the operation is invoked, passing
    the index as the first argument and the value as the second argument.  If the operation used to declare the indexed property setter
    did not have an identifier, then the interface definition must be accompanied
    by a description of how to <dfn id="dfn-set-the-value-of-an-existing-indexed-property" export>set the value of an existing indexed property</dfn>
    and how to <dfn id="dfn-set-the-value-of-a-new-indexed-property" export>set the value of a new indexed property</dfn>
    for a given property index and value.

<div class="note">

    Note that if an [=indexed property getter=] or
    [=indexed property setters|setter=]
    is specified using an [=operation=] with an [=identifier=],
    then indexing an object with an integer that is not a [=supported property indices|supported property index=]
    does not necessarily elicit the same behavior as invoking the operation with that index.  The actual behavior in this
    case is language binding specific.

    In the ECMAScript language binding, a regular property lookup is done.  For example, take the following IDL:

    <pre highlight="webidl">
        [Exposed=Window]
        interface A {
          getter DOMString toWord(unsigned long index);
        };
    </pre>

    Assume that an object implementing <code class="idl">A</code> has [=supported property indices=]
    in the range 0 ≤ <var ignore>index</var> &lt; 2.  Also assume that toWord is defined to return
    its argument converted into an English word.  The behavior when invoking the
    [=operation=] with an out of range index
    is different from indexing the object directly:

    <pre highlight="js">
        var a = getA();

        a.toWord(0);  // Evalautes to "zero".
        a[0];         // Also evaluates to "zero".

        a.toWord(5);  // Evaluates to "five".
        a[5];         // Evaluates to undefined, since there is no property "5".
    </pre>
</div>

<div class="example">

    The following [=IDL fragment=] defines an interface
    <code class="idl">OrderedMap</code> which allows
    retrieving and setting values by name or by index number:

    <pre highlight="webidl">
        [Exposed=Window]
        interface OrderedMap {
          readonly attribute unsigned long size;

          getter any getByIndex(unsigned long index);
          setter void setByIndex(unsigned long index, any value);

          getter any get(DOMString name);
          setter void set(DOMString name, any value);
        };
    </pre>

    Since all of the special operations are declared using
    operations with identifiers, the only additional prose
    that is necessary is that which describes what keys those sets
    have.  Assuming that the <code>get()</code> operation is
    defined to return <emu-val>null</emu-val> if an
    attempt is made to look up a non-existing entry in the
    <code class="idl">OrderedMap</code>, then the following
    two sentences would suffice:

    <blockquote>

        An object <var ignore>map</var> implementing <code class="idl">OrderedMap</code>
        supports indexed properties with indices in the range
        0 ≤ <var ignore>index</var> &lt; <code>map.size</code>.

        Such objects also support a named property for every name that,
        if passed to <code>get()</code>, would return a non-null value.

    </blockquote>

    As described in [[#es-legacy-platform-objects]],
    an ECMAScript implementation would create
    properties on a [=legacy platform object=] implementing
    <code class="idl">OrderedMap</code> that correspond to
    entries in both the named and indexed property sets.
    These properties can then be used to interact
    with the object in the same way as invoking the object’s
    methods, as demonstrated below:

    <pre highlight="js">
        // Assume map is a legacy platform object implementing the OrderedMap interface.
        var map = getOrderedMap();
        var x, y;

        x = map[0];       // If map.length &gt; 0, then this is equivalent to:
                          //
                          //   x = map.getByIndex(0)
                          //
                          // since a property named "0" will have been placed on map.
                          // Otherwise, x will be set to undefined, since there will be
                          // no property named "0" on map.

        map[1] = false;   // This will do the equivalent of:
                          //
                          //   map.setByIndex(1, false)

        y = map.apple;    // If there exists a named property named "apple", then this
                          // will be equivalent to:
                          //
                          //   y = map.get('apple')
                          //
                          // since a property named "apple" will have been placed on
                          // map.  Otherwise, y will be set to undefined, since there
                          // will be no property named "apple" on map.

        map.berry = 123;  // This will do the equivalent of:
                          //
                          //   map.set('berry', 123)

        delete map.cake;  // If a named property named "cake" exists, then the "cake"
                          // property will be deleted, and then the equivalent to the
                          // following will be performed:
                          //
                          //   map.remove("cake")
    </pre>
</div>


<h5 id="idl-named-properties" dfn export>Named properties</h5>

An [=interface=] that defines a [=named property getter=]
is said to <dfn id="dfn-support-named-properties" export>support named properties</dfn>.
By extension, a [=platform object=]
is said to [=support named properties=] if
it implements an [=interface=] that itself does.

If an interface [=support named properties|supports named properties=],
then the interface definition must be accompanied by
a description of the ordered set of names that can be used to index the object
at any given time.  These names are called the
<dfn id="dfn-supported-property-names" export>supported property names</dfn>.

Named property getters and deleters must
be declared to take a single {{DOMString}} argument.
Named property setters must
be declared to take two arguments, where the first is a {{DOMString}}.

<pre highlight="webidl" class="syntax">
    interface interface_identifier {
      getter type identifier(DOMString identifier);
      setter type identifier(DOMString identifier, type identifier);
      deleter type identifier(DOMString identifier);

      getter type (DOMString identifier);
      setter type (DOMString identifier, type identifier);
      deleter type (DOMString identifier);
    };
</pre>

The following requirements apply to the definitions of named property getters, setters and deleters:

*   If a [=named property getter=] was specified using an [=operation=]
    with an [=identifier=],
    then the value returned when indexing the object with a given [=supported property name=]
    is the value that would be returned by invoking the operation, passing
    the name as its only argument.  If the operation used to declare the named property getter
    did not have an identifier, then the interface definition must be accompanied
    by a description of how to <dfn id="dfn-determine-the-value-of-a-named-property" export>determine the value of a named property</dfn>
    for a given property name.
*   If a [=named property setter=] was specified using an operation
    with an identifier,
    then the behavior that occurs when indexing the object for property assignment with a given supported property name and value
    is the same as if the operation is invoked, passing
    the name as the first argument and the value as the second argument.  If the operation used to declare the named property setter
    did not have an identifier, then the interface definition must be accompanied
    by a description of how to <dfn id="dfn-set-the-value-of-an-existing-named-property" export>set the value of an existing named property</dfn>
    and how to <dfn id="dfn-set-the-value-of-a-new-named-property" export>set the value of a new named property</dfn>
    for a given property name and value.
*   If a [=named property deleter=] was specified using an operation
    with an identifier,
    then the behavior that occurs when indexing the object for property deletion with a given supported property name
    is the same as if the operation is invoked, passing
    the name as the only argument.  If the operation used to declare the named property deleter
    did not have an identifier, then the interface definition must be accompanied
    by a description of how to <dfn id="dfn-delete-an-existing-named-property" export>delete an existing named property</dfn>
    for a given property name.

Note: As with [=indexed properties=],
if an [=named property getter=],
[=named property setters|setter=] or
[=named property deleters|deleter=]
is specified using an [=operation=] with an [=identifier=],
then indexing an object with a name that is not a [=supported property name=]
does not necessarily elicit the same behavior as invoking the operation with that name; the behavior
is language binding specific.


<h4 id="idl-static-attributes-and-operations">Static attributes and operations</h4>

<dfn id="dfn-static-attribute" export>Static attributes</dfn> and
<dfn id="dfn-static-operation" export>static operations</dfn> are ones that
are not associated with a particular instance of the
[=interface=]
on which it is declared, and is instead associated with the interface
itself.  Static attributes and operations are declared by using the
<emu-t>static</emu-t> keyword in their declarations.

It is language binding specific whether it is possible to invoke
a static operation or get or set a static attribute through a reference
to an instance of the interface.

<pre class="grammar" id="prod-StaticMember">
    StaticMember :
        "static" StaticMemberRest
</pre>

<pre class="grammar" id="prod-StaticMemberRest">
    StaticMemberRest :
        ReadOnly AttributeRest
        RegularOperation
</pre>

<div class="example">

    The following [=IDL fragment=] defines an interface
    <code class="idl">Circle</code> that has a static
    operation declared on it:

    <pre highlight="webidl">
        [Exposed=Window]
        interface Point { /* ... */ };

        [Exposed=Window]
        interface Circle {
          attribute double cx;
          attribute double cy;
          attribute double radius;

          static readonly attribute long triangulationCount;
          static Point triangulate(Circle c1, Circle c2, Circle c3);
        };
    </pre>

    In the ECMAScript language binding, the [=function object=] for
    <code>triangulate</code> and the accessor property for <code>triangulationCount</code>
    will exist on the [=interface object=]
    for <code class="idl">Circle</code>:

    <pre highlight="js">
        var circles = getCircles();           // an Array of Circle objects

        typeof Circle.triangulate;            // Evaluates to "function"
        typeof Circle.triangulationCount;     // Evaluates to "number"
        Circle.prototype.triangulate;         // Evaluates to undefined
        Circle.prototype.triangulationCount;  // Also evaluates to undefined
        circles[0].triangulate;               // As does this
        circles[0].triangulationCount;        // And this

        // Call the static operation
        var triangulationPoint = Circle.triangulate(circles[0], circles[1], circles[2]);

        // Find out how many triangulations we have done
        window.alert(Circle.triangulationCount);
    </pre>
</div>


<h4 id="idl-overloading">Overloading</h4>

If a [=regular operation=]
or [=static operation=]
defined on an [=interface=]
has an [=identifier=]
that is the same as the identifier of another operation on that
interface of the same kind (regular or static), then the operation is said to be
<dfn id="dfn-overloaded" export>overloaded</dfn>.  When the identifier
of an overloaded operation is used to invoke one of the
operations on an object that implements the interface, the
number and types of the arguments passed to the operation
determine which of the overloaded operations is actually
invoked.
[=Constructor operations=] can be overloaded too.
There are some restrictions on the arguments
that overloaded operations and constructors can be
specified to take, and in order to describe these restrictions,
the notion of an <em>effective overload set</em> is used.

[=Operations=] must not be overloaded across
[=interface=],
[=partial interface=],
[=interface mixin=], and
[=partial interface mixin=]
definitions.

<div class="note">

    For example, the overloads for both <var ignore>f</var> and <var ignore>g</var>
    are disallowed:

    <pre highlight="webidl">
        [Exposed=Window]
        interface A {
          void f();
        };

        partial interface A {
          void f(double x);
          void g();
        };

        partial interface A {
          void g(DOMString x);
        };
    </pre>

    Note that [=constructor operations=] and
    [{{NamedConstructor}}]
    [=extended attributes=] are disallowed from appearing
    on [=partial interface=] definitions,
    so there is no need to also disallow overloading for constructors.

</div>

An <dfn id="dfn-effective-overload-set" export>effective overload set</dfn>
represents the allowable invocations for a particular
[=operation=],
constructor (specified with a [=constructor operation=]
or [{{NamedConstructor}}]), or
[=callback function=].
The algorithm to [=compute the effective overload set=]
operates on one of the following four types of IDL constructs, and listed with them below are
the inputs to the algorithm needed to compute the set.

 :  For regular operations
 :  For static operations
 :: *   the [=interface=] on which the [=operations=] are to be found
    *   the [=identifier=] of the operations
    *   the number of arguments to be passed
 :  For constructors
 :: *   the [=interface=] on which the [=constructor operations=] are to be found
    *   the number of arguments to be passed
 :  For named constructors
 :: *   the [=interface=] on which the [{{NamedConstructor}}] [=extended attributes=] are to be found
    *   the [=identifier=] of the named constructors
    *   the number of arguments to be passed

An [=effective overload set=] is used, among other things, to determine whether there are
ambiguities in the overloaded operations and constructors specified on an interface.

The [=set/items=] of an [=effective overload set=] are [=tuples=] of the form
([=effective overload set tuple/callable=], [=type list=], [=optionality list=])
whose [=tuple/items=] are described below:

*   A <dfn for="effective overload set tuple">callable</dfn> is an [=operation=]
    if the [=effective overload set=] is for [=regular operations=],
    [=static operations=], or [=constructor operations=]; and it is an [=extended attribute=]
    if the [=effective overload set=] is for [=named constructors=].
*   A <dfn>type list</dfn> is a [=list=] of IDL types.
*   An <dfn>optionality list</dfn> is a [=list=] of
    three possible <dfn id="dfn-optionality-value" export>optionality values</dfn>
    – "required", "optional" or "variadic" –
    indicating whether the argument at a given index was
    declared as being [=optional argument|optional=]
    or corresponds to a [=variadic=] argument.

Each [=tuple=] represents an allowable invocation of the operation,
constructor, or callback function with an argument value list of the given types.
Due to the use of [=optional arguments=]
and [=variadic=] operations
and constructors, there may be multiple items in an [=effective overload set=] identifying
the same operation or constructor.

<div algorithm="compute the effective overload set">
    The algorithm below describes how to <dfn>compute the effective overload set</dfn>.
    The following input variables are used, if they are required:

    *   the identifier of the operation or named constructor is |A|
    *   the argument count is |N|
    *   the interface is |I|

    Whenever an argument of an extended attribute is mentioned,
    it is referring to an argument of the extended attribute’s
    [=takes a named argument list|named argument list=].

    1.  Let |S| be an [=ordered set=].
    1.  Let |F| be an [=ordered set=] with [=set/items=] as follows,
        according to the kind of [=effective overload set=]:
        <dl class="switch">
             :  For regular operations
             :: The elements of |F| are the [=regular operations=] with
                identifier |A| defined on interface |I|.
             :  For static operations
             :: The elements of |F| are the [=static operations=] with
                identifier |A| defined on interface |I|.
             :  For constructors
             :: The elements of |F| are the
                [=constructor operations=] on interface |I|.
             :  For named constructors
             :: The elements of |F| are the
                [{{NamedConstructor}}]
                [=extended attributes=] on interface |I| whose
                [=takes a named argument list|named argument lists’=]
                identifiers are |A|.
        </dl>

    1.  Let |maxarg| be the maximum number of arguments the operations,
        constructor extended attributes or callback functions in |F| are declared to take.
        For [=variadic=] operations and constructor extended attributes,
        the argument on which the ellipsis appears counts as a single argument.

        Note: So <code>void f(long x, long... y);</code> is considered to be declared to take two arguments.
    1.  Let |max| be <a abstract-op>max</a>(|maxarg|, |N|).
    1.  [=set/For each=] operation or extended attribute |X| in |F|:
        1.  Let |arguments| be the [=list=] of arguments |X| is declared to take.
        1.  Let |n| be the [=list/size=] of |arguments|.
        1.  Let |types| be a [=type list=].
        1.  Let |optionalityValues| be an [=optionality list=].
        1.  [=list/For each=] |argument| in |arguments|:
            1.  [=list/Append=] the type of |argument| to |types|.
            1.  [=list/Append=] "variadic" to |optionalityValues| if |argument| is a final, variadic argument,
                "optional" if |argument| is [=optional argument|optional=],
                and "required" otherwise.
        1.  [=set/Append=] the [=tuple=] (|X|, |types|, |optionalityValues|) to |S|.
        1.  If |X| is declared to be [=variadic=], then:
            1.  [=list/For each=] |i| in [=the range=] |n| to |max| − 1, inclusive:
                1.  Let |t| be a [=type list=].
                1.  Let |o| be an [=optionality list=].
                1.  [=list/For each=] |j| in [=the range=] 0 to |n| − 1, inclusive:
                    1.  [=list/Append=] |types|[|j|] to |t|.
                    1.  [=list/Append=] |optionalityValues|[|j|] to |o|.
                1.  [=list/For each=] |j| in [=the range=] |n| to |i|, inclusive:
                    1.  [=list/Append=] |types|[|n| − 1] to |t|.
                    1.  [=list/Append=] "variadic" to |o|.
                1.  [=set/Append=] the [=tuple=] (|X|, |t|, |o|) to |S|.
        1.  Let |i| be |n| − 1.
        1.  [=iteration/While=] |i| ≥ 0:
            1.  If |arguments|[|i|] is not [=optional argument|optional=]
                (i.e., it is not marked as "optional" and is not
                a final, variadic argument), then [=iteration/break=].
            1.  Let |t| be a [=type list=].
            1.  Let |o| be an [=optionality list=].
            1.  [=list/For each=] |j| in [=the range=] 0 to |i| − 1, inclusive:
                1.  [=list/Append=] |types|[|j|] to |t|.
                1.  [=list/Append=] |optionalityValues|[|j|] to |o|.
            1.  [=set/Append=] the [=tuple=] (|X|, |t|, |o|) to |S|.

                Note: if |i| is 0, this means to add to |S| the tuple (|X|, « », « »);
                (where "« »" represents an [=list/is empty|empty list=]).
            1.  Set |i| to |i| − 1.
    1.  Return |S|.
</div>

<div class="example">

    For the following interface:

    <pre highlight="webidl">
        [Exposed=Window]
        interface A {
          /* f1 */ void f(DOMString a);
          /* f2 */ void f(Node a, DOMString b, double... c);
          /* f3 */ void f();
          /* f4 */ void f(Event a, DOMString b, optional DOMString c, double... d);
        };
    </pre>

    assuming <code class="idl">Node</code> and <code class="idl">Event</code>
    are two other interfaces of which no object can implement both,
    the [=effective overload set=]
    for [=regular operations=] with
    identifier <code>f</code> and argument count 4 is:

    <pre class="set">
      «
        (f1, « DOMString »,                           « required »),
        (f2, « Node, DOMString »,                     « required, required »),
        (f2, « Node, DOMString, double »,             « required, required, variadic »),
        (f2, « Node, DOMString, double, double »,     « required, required, variadic, variadic »),
        (f3, « »,                                     « »),
        (f4, « Event, DOMString »,                    « required, required »),
        (f4, « Event, DOMString, DOMString »,         « required, required, optional »),
        (f4, « Event, DOMString, DOMString, double », « required, required, optional, variadic »)
      »
    </pre>
</div>

Two types are <dfn id="dfn-distinguishable" export>distinguishable</dfn> if
the following algorithm returns <i>true</i>.

<ol class="algorithm">
1.  If one type [=includes a nullable type=]
    and the other type either
    [=includes a nullable type=],
    is a [=union type=] with [=flattened member types=]
    including a [=dictionary type=], or
    is a [=dictionary type=],
    return <i>false</i>.
    <div class="example" id="example-distinguishability-nullable">
        None of the following pairs are distinguishable:
        <ul>
            <li>
                <code>{{double}}?</code> and
                <code>Dictionary1</code>
            </li>
            <li>
                <code>(Interface1 or {{long}})?</code> and
                <code>(Interface2 or {{DOMString}})?</code>
            </li>
            <li>
                <code>(Interface1 or {{long}}?)</code> and
                <code>(Interface2 or {{DOMString}})?</code>
            </li>
            <li>
                <code>(Interface1 or {{long}}?)</code> and
                <code>(Interface2 or {{DOMString}}?)</code>
            </li>
            <li>
                <code>(Dictionary1 or {{long}})</code> and
                <code>(Interface2 or {{DOMString}})?</code>
            </li>
            <li>
                <code>(Dictionary1 or {{long}})</code> and
                <code>(Interface2 or {{DOMString}}?)</code>
            </li>
        </ul>
    </div>
1.  If both types are either a [=union type=] or [=nullable type|nullable=] [=union type=],
    return <i>true</i> if each member type of the one
    is distinguishable with each member type of the other,
    or <i>false</i> otherwise.
1.  If one type is a [=union type=] or nullable union type,
    return <i>true</i> if each
    [=member type=] of the union type is distinguishable
    with the non-union type,
    or <i>false</i> otherwise.
1.  Consider the two "innermost" types derived by taking each type's [=annotated types/inner type=]
    if it is an [=annotated type=], and then taking its [=nullable types/inner type=] inner type
    if the result is a [=nullable type=]. If these two innermost types appear or are in categories
    appearing in the following table and there is a “●” mark in the corresponding entry
    or there is a letter in the corresponding entry and the designated additional
    requirement below the table is satisfied, then return <i>true</i>.
    Otherwise return <i>false</i>.

    Categories:
    <dl>
        <dt>interface-like</dt>
        <dd>
            * [=interface types=]
            * [=buffer source types=]
        <dt>dictionary-like</dt>
        <dd>
            * [=dictionary types=]
            * [=record types=]
            * [=callback interface types=]
        <dt>sequence-like</dt>
        <dd>
            * [=sequence types=]
            * [=frozen array types=]
    </dl>

    <table id="distinguishable-table" class="matrix data complex">
        <tr>
            <th class="corner"></th>
                <th><div>
                    <span>boolean</span>
            </div></th>
                <th><div>
                    <span>numeric types</span>
            </div></th>
                <th><div>
                    <span>string types</span>
            </div></th>
                <th><div>
                    <span>object</span>
            </div></th>
                <th><div>
                    <span>symbol</span>
            </div></th>
                <th><div>
                    <span>interface-like</span>
                </div></th>
                <th><div>
                    <span>callback function</span>
            </div></th>
                <th><div>
                    <span>dictionary-like</span>
            </div></th>
                <th><div>
                    <span>sequence-like</span>
            </div></th>
        </tr>
        <tr>
            <th>boolean</th>
            <td></td>
            <td>●</td>
            <td>●</td>
            <td>●</td>
            <td>●</td>
            <td>●</td>
            <td>●</td>
            <td>●</td>
            <td>●</td>
        </tr>
        <tr>
            <th>numeric types</th>
            <td class="belowdiagonal"></td>
            <td></td>
            <td>●</td>
            <td>●</td>
            <td>●</td>
            <td>●</td>
            <td>●</td>
            <td>●</td>
            <td>●</td>
        </tr>
        <tr>
            <th>string types</th>
            <td class="belowdiagonal"></td>
            <td class="belowdiagonal"></td>
            <td></td>
            <td>●</td>
            <td>●</td>
            <td>●</td>
            <td>●</td>
            <td>●</td>
            <td>●</td>
        </tr>
        <tr>
            <th>object</th>
            <td class="belowdiagonal"></td>
            <td class="belowdiagonal"></td>
            <td class="belowdiagonal"></td>
            <td></td>
            <td>●</td>
            <td></td>
            <td></td>
            <td></td>
            <td></td>
        </tr>
        <tr>
            <th>symbol</th>
            <td class="belowdiagonal"></td>
            <td class="belowdiagonal"></td>
            <td class="belowdiagonal"></td>
            <td class="belowdiagonal"></td>
            <td></td>
            <td>●</td>
            <td>●</td>
            <td>●</td>
            <td>●</td>
        </tr>
        <tr>
            <th>interface-like</th>
            <td class="belowdiagonal"></td>
            <td class="belowdiagonal"></td>
            <td class="belowdiagonal"></td>
            <td class="belowdiagonal"></td>
            <td class="belowdiagonal"></td>
            <td>(a)</td>
            <td>●</td>
            <td>●</td>
            <td>●</td>
        </tr>
        <tr>
            <th>callback function</th>
            <td class="belowdiagonal"></td>
            <td class="belowdiagonal"></td>
            <td class="belowdiagonal"></td>
            <td class="belowdiagonal"></td>
            <td class="belowdiagonal"></td>
            <td class="belowdiagonal"></td>
            <td></td>
            <td></td>
            <td>●</td>
        </tr>
        <tr>
            <th>dictionary-like</th>
            <td class="belowdiagonal"></td>
            <td class="belowdiagonal"></td>
            <td class="belowdiagonal"></td>
            <td class="belowdiagonal"></td>
            <td class="belowdiagonal"></td>
            <td class="belowdiagonal"></td>
            <td class="belowdiagonal"></td>
            <td></td>
            <td>●</td>
        </tr>
        <tr>
            <th>sequence-like</th>
            <td class="belowdiagonal"></td>
            <td class="belowdiagonal"></td>
            <td class="belowdiagonal"></td>
            <td class="belowdiagonal"></td>
            <td class="belowdiagonal"></td>
            <td class="belowdiagonal"></td>
            <td class="belowdiagonal"></td>
            <td class="belowdiagonal"></td>
            <td></td>
        </tr>
    </table>

    <ol type="a">
        1.  The two identified interface-like types are
            not the same, and no single [=platform object=] implements both
            interface-like types.
    </ol>

    <div class="example" id="example-distinguishability-diff-types">
        {{double}} and {{DOMString}} are distinguishable because
        there is a ● at the intersection of [=numeric types=] with [=string types=].
    </div>

    <div class="example" id="example-distinguishability-same-category">
        {{double}} and {{long}} are not distinguishable because they are both [=numeric types=],
        and there is no ● or letter at the intersection of [=numeric types=] with [=numeric types=].
    </div>

    <div class="example" id="example-distinguishability-callback-interfaces">
        Given:

        <pre highlight="idl">
            callback interface CBIface {
                void handle();
            };

            [Exposed=Window]
            interface Iface {
                attribute DOMString attr2;
            };

            dictionary Dict {
                DOMString field1;
            };
        </pre>

        <code>CBIface</code> is distinguishable from <code>Iface</code>
        because there's a ● at the intersection of dictionary-like and interface-like,
        but it is not distinguishable from <code>Dict</code>
        because there's no ● at the intersection of dictionary-like and itself.
    </div>

    <div class="example" id="example-distinguishability-promises">
        [=Promise types=] do not appear in the above table, and as a consequence are
        not distinguishable with any other type.
    </div>

</ol>

If there is more than one [=list/item=] in an [=effective overload set=]
that has a given [=type list=] [=list/size=],
then for those items there must be an index |i| such that
for each pair of items the types at index |i| are [=distinguishable=].
The lowest such index is termed the <dfn id="dfn-distinguishing-argument-index" export>distinguishing argument index</dfn>
for the items of the [=effective overload set=] with the given type list size.

<div class="example">

    Consider the [=effective overload set=] shown in the previous example.
    There are multiple items in the set with type lists 2, 3 and 4.
    For each of these type list size, the [=distinguishing argument index=] is 0, since <code class="idl">Node</code> and
    <code class="idl">Event</code> are [=distinguishable=].

    The following use of overloading however is invalid:

    <pre highlight="webidl">
        [Exposed=Window]
        interface B {
          void f(DOMString x);
          void f(USVString x);
        };
    </pre>

    since {{DOMString}} and {{USVString}} are not distinguishable.

</div>

In addition, for each index |j|, where |j| is less than the
[=distinguishing argument index=]
for a given type list size, the types at index |j| in
all of the items’ type lists must be the same,
and the [=optionality values=] at index |j| in all of the items’ optionality lists must
be the same.

<div class="example">

    The following is invalid:

    <pre highlight="webidl">
        [Exposed=Window]
        interface B {
          /* f1 */ void f(DOMString w);
          /* f2 */ void f(long w, double x, Node y, Node z);
          /* f3 */ void f(double w, double x, DOMString y, Node z);
        };
    </pre>

    For argument count 4, the [=effective overload set=] is:

    <pre class="set">
      «
        (f1, « DOMString »,                       « required »),
        (f2, « long, double, Node, Node »,        « required, required, required, required »),
        (f3, « double, double, DOMString, Node », « required, required, required, required »)
      »
    </pre>

    Looking at items with type list size 4, the
    [=distinguishing argument index=]
    is 2, since <code class="idl">Node</code> and
    {{DOMString}} are [=distinguishable=].
    However, since the arguments in these two overloads at index 0 are different,
    the overloading is invalid.

</div>


<h5 id="idl-overloading-vs-union">Overloading vs. union types</h5>

<i>This section is informative.</i>

<div class="non-normative">

For specifications defining IDL [=operations=], it might seem that [=overloaded|overloads=] and a
combination of [=union types=] and [=optional arguments=] have some feature overlap.

It is first important to note that [=overloaded|overloads=] have different behaviors than [=union
types=] or [=optional arguments=], and one <em>cannot</em> be fully defined using the other (unless,
of course, additional prose is provided, which can defeat the purpose of the Web IDL type system).
For example, consider the {{CanvasDrawPath/stroke()}} operations defined on the {{CanvasDrawPath}}
interface [[HTML]]:

<pre highlight="webidl">
    interface CanvasDrawPathExcerpt {
      void stroke();
      void stroke(Path2D path);
    };
</pre>

Per the ECMAScript language binding, calling <code>stroke(undefined)</code> on an object
implementing <code class="idl">CanvasDrawPathExcerpt</code> would attempt to call the second
overload, yielding a {{TypeError}} since <emu-val>undefined</emu-val> cannot be <a
href="#es-to-interface">converted</a> to a {{Path2D}}. However, if the operations were instead
defined with [=optional arguments=] and merged into one,

<pre highlight="webidl">
    interface CanvasDrawPathExcerptOptional {
      void stroke(optional Path2D path);
    };
</pre>

the [=overload resolution algorithm=] would treat the <var ignore>path</var> argument as [=not
present=] given the same call <code>stroke(undefined)</code>, and not throw any exceptions.

Note: For this particular example, the latter behavior is actually what Web developers would
generally expect. If {{CanvasDrawPath}} were to be designed today, [=optional arguments=] would be
used for <code class="idl">stroke()</code>.

Additionally, there are semantic differences as well. [=Union types=] are usually used in the sense
that "any of the types would work in about the same way". In contrast, [=overloaded=] operations are
designed to map well to language features such as C++ overloading, and are usually a better fit for
operations with more substantial differences in what they do given arguments of different types.
However, in most cases, operations with such substantial differences are best off with different
names to avoid confusion for Web developers, since the ECMAScript language does not provide
language-level overloading. As such, overloads are rarely appropriate for new APIs, instead often
appearing in legacy APIs or in specialized circumstances.

That being said, we offer the following recommendations and examples in case of difficulties to
determine what Web IDL language feature to use:

*   In the unusual case where the operation needs to return values of different types for different
    argument types, [=overloaded|overloading=] will result in more expressive IDL fragments. <span
    class="note">This is almost never appropriate API design, and separate operations with distinct
    names usually are a better choice for such cases.</span>

    Suppose there is an operation <code class="idl">calculate()</code> that accepts a {{long}},
    {{DOMString}}, or <code class="idl">CalculatableInterface</code> (an [=interface type=]) as its
    only argument, and returns a value of the same type as its argument. It would be clearer to
    write the IDL fragment using [=overloaded=] operations as

    <pre highlight="webidl">
        interface A {
          long calculate(long input);
          DOMString calculate(DOMString input);
          CalculatableInterface calculate(CalculatableInterface input);
        };
    </pre>

    than using a [=union type=] with a [=typedef=] as

    <pre highlight="webidl">
        typedef (long or DOMString or CalculatableInterface) Calculatable;
        interface A {
          Calculatable calculate(Calculatable input);
        };
    </pre>

    which does not convey the fact that the return value is always of the same type as <var
    ignore>input</var>.

    The problem is exacerbated when one of the overloads has a return type of {{void}}, since
    [=union types=] cannot even contain {{void}} as a [=member type=]. In that case, a return type
    of {{any}} needs to be used with appropriate prose defining the return type, further decreasing
    expressiveness.

    If the specified <code class="idl">calculate()</code> is a new API and does not have any
    compatibility concerns, it is suggested to use different names for the overloaded operations,
    perhaps as

    <pre highlight="webidl">
        interface A {
          long calculateNumber(long input);
          DOMString calculateString(DOMString input);
          CalculatableInterface calculateCalculatableInterface(CalculatableInterface input);
        };
    </pre>

    which allows Web developers to write explicit and unambiguous code.

*   When the operation has significantly different semantics for different argument types or
    lengths, [=overloaded|overloading=] is preferred. Again, in such scenarios, it is usually better
    to create separate operations with distinct names, but legacy APIs sometimes follow this
    pattern.

    As an example, the {{CSS/supports(property, value)}} and {{CSS/supports(conditionText)}}
    operations of the {{CSS}} interface are defined as the
    following IDL fragment [[CSS3-CONDITIONAL]] [[CSSOM]].

    <pre highlight="webidl">
        partial interface CSS {
          static boolean supports(CSSOMString property, CSSOMString value);
          static boolean supports(CSSOMString conditionText);
        };
    </pre>

    Using [=optional arguments=] one can rewrite the IDL fragment as follows:

    <pre highlight="webidl">
        partial interface CSSExcerptOptional {
          static boolean supports(CSSOMString propertyOrConditionText, optional CSSOMString value);
        };
    </pre>

    Even though the IDL is shorter in the second version, two distinctively different concepts are
    conflated in the first argument. Without [=overloaded|overloads=], the question "is <var
    ignore>property</var> or <var ignore>conditionText</var> paired with <var ignore>value</var>?"
    is much more difficult to answer without reading the prose definition of the operation. This
    makes the second version remarkably less readable than the first.

    Another consideration is that the prose for [=overloaded=] operations can be specified in
    separate blocks, which can aid in both reading and writing specifications. This is not the case
    for [=optional arguments=]. This means that in the first case the specification author can write
    the prose definition of the operations as:

    <div algorithm="execute supports() with overloads">

        The <code class="idl">supports(<var ignore>property</var>, <var ignore>value</var>)</code>
        method, when called, must run these steps:

        1.  …

        ----

        The <code class="idl">supports(<var ignore>conditionText</var>)</code> method, when called,
        must run these steps:

        1.  …

    </div>

    Yet using <var ignore>value</var> as an [=optional argument=], the specification author has to
    use more boilerplate-style text to effectively replicate the [=overload resolution algorithm=].

    <div algorithm="execute supports() with optional argument">

        The <code class="idl">supports(|propertyOrConditionText|, |value|)</code> method, when
        called, must run these steps:

        1.  If |value| is given, then:
            1.  Let <var ignore>property</var> be |propertyOrConditionText|.
            1.  …
        1.  Otherwise:
            1.  Let <var ignore>conditionText</var> be |propertyOrConditionText|.
            1.  …

    </div>

    If the two overloads have little to no shared parts, it is better to leave overload resolution
    to the IDL mechanism.

*   If the operation accepts multiple types for multiple arguments with no coupling between types of
    different arguments, [=union types=] can sometimes be the only viable solution.

    <pre highlight="webidl">
        typedef (long long or DOMString or CalculatableInterface) SupportedArgument;
        interface A {
          void add(SupportedArgument operand1, SupportedArgument operand2);
        };
    </pre>

    For the <code class="idl">add()</code> operation above, to specify it using
    [=overloaded|overloads=] would require

    <pre highlight="webidl">
        interface A {
          void add(long long operand1, long long operand2);
          void add(long long operand1, DOMString operand2);
          void add(long long operand1, CalculatableInterface operand2);
          void add(DOMString operand1, long long operand2);
          void add(DOMString operand1, DOMString operand2);
          void add(DOMString operand1, CalculatableInterface operand2);
          void add(CalculatableInterface operand1, long long operand2);
          void add(CalculatableInterface operand1, DOMString operand2);
          void add(CalculatableInterface operand1, CalculatableInterface operand2);
        };
    </pre>

    and nine times the corresponding prose!

*   Specification authors are encouraged to treat missing argument and <emu-val>undefined</emu-val>
    argument the same way in the ECMAScript language binding.

    Given the following IDL fragment:

    <pre highlight="webidl">
        interface A {
          void foo();
          void foo(Node? arg);
        };
    </pre>

    Using the ECMAScript language binding, calling <code>foo(undefined)</code> and
    <code>foo(null)</code> would both run the steps corresponding to the <code
    class="idl">foo(|arg|)</code> operation, with |arg| set to null, while <code>foo()</code> alone
    would go to the first overload. This can be a surprising behavior for many API users. Instead,
    specification authors are encouraged to use an [=optional argument=], which would categorize
    both <code>foo()</code> and <code>foo(undefined)</code> as "|arg| is [=not
    present=]".

    <pre highlight="webidl">
        interface A {
          void foo(optional Node? arg);
        };
    </pre>

    In general, optionality is best expressed using the <emu-t>optional</emu-t> keyword, and not
    using overloads.

When the case fits none of the categories above, it is up to the specification author to choose the
style, since it is most likely that either style would sufficiently and conveniently describe the
intended behavior. However, the definition and <a href="#es-to-union">conversion algorithms</a> of
[=union types=] and [=optional arguments=] are simpler to implement and reason about than [=overload
resolution algorithm|those=] of [=overloaded|overloads=], and usually result in more idiomatic APIs
in the ECMAScript language binding. Thus, unless any other considerations apply, [=union types=]
(and/or [=optional arguments=]) are the default choice.

Specifications are also free to mix and match union types and overloads, if the author finds it
appropriate and convenient.

</div>


<h4 id="idl-iterable">Iterable declarations</h4>

An [=interface=] can be declared to be
<dfn id="dfn-iterable" export>iterable</dfn> by using an <dfn id="dfn-iterable-declaration" export>iterable declaration</dfn>
(matching <emu-nt><a href="#prod-Iterable">Iterable</a></emu-nt>) in the body of the interface.

<pre highlight="webidl" class="syntax">
    interface interface_identifier {
      iterable&lt;value_type&gt;;
      iterable&lt;key_type, value_type&gt;;
    };
</pre>

Objects implementing an interface that is declared to be iterable
support being iterated over to obtain a sequence of values.

Note: In the ECMAScript language binding, an interface that is iterable
will have <code class="idl">entries</code>, <code class="idl">forEach</code>,
<code class="idl">keys</code>, <code class="idl">values</code>, and {{@@iterator}}
properties on its [=interface prototype object=].

If a single type parameter is given, then the interface has a
<dfn id="dfn-value-iterator" export>value iterator</dfn> and provides
values of the specified type.
If two type parameters are given, then the interface has a
<dfn id="dfn-pair-iterator" export>pair iterator</dfn> and provides
[=value pairs=] with the given types.

A <dfn>value pair</dfn>, given a key type and a value type, is a [=/struct=] with two
[=struct/items=]:
1.  an [=struct/item=] whose [=struct/name=] is "key", which is referred to as the [=value pair=]'s
    <dfn for="value pair">key</dfn>, and whose value is an IDL value of the key type;
1.  an [=struct/item=] whose [=struct/name=] is "value", which is referred to as the
    [=value pair=]'s <dfn for="value pair">value</dfn>, and whose value is an IDL value of the
    value type.

A [=value iterator=]
must only be declared on an interface
that [=support indexed properties|supports indexed properties=].
The value-type of the [=value iterator=]
must be the same as the type returned by
the [=indexed property getter=].
A [=value iterator=] is implicitly
defined to iterate over the object’s indexed properties.

A [=pair iterator=]
must not be declared on an interface
that [=support indexed properties|supports indexed properties=].

Prose accompanying an [=interface=] with a [=pair iterator=] must define a [=/list=] of
[=value pairs=] for each instance of the [=interface=], which is the list of
<dfn id="dfn-value-pairs-to-iterate-over" export>value pairs to iterate over</dfn>.

<div class="note">

    The ECMAScript forEach method that is generated for a
    [=value iterator=]
    invokes its callback like Array.prototype.forEach does, and the forEach
    method for a [=pair iterator=]
    invokes its callback like Map.prototype.forEach does.

    Since [=value iterators=]
    are currently allowed only on interfaces that
    [=support indexed properties=],
    it makes sense to use an Array-like forEach method.
    There may be a need for [=value iterators=]
    (a) on interfaces that do not
    [=support indexed properties=],
    or (b) with a forEach method that instead invokes its callback like
    Set.protoype.forEach (where the key is the same as the value).
    If you’re creating an API that needs such a forEach method, please
    <a href="https://github.com/heycam/webidl/issues/new?title=Enhancement%20request%20for%20Iterables">file an issue</a>.

</div>

Note: This is how [=array iterator objects=] work.
For interfaces that [=support indexed properties=],
the iterator objects returned by <code class="idl">entries</code>,
<code class="idl">keys</code>, <code class="idl">values</code>, and {{@@iterator}} are
actual [=array iterator objects=].

Interfaces with iterable declarations must not
have any [=interface members=]
named "<code>entries</code>", "<code>forEach</code>",
"<code>keys</code>", or "<code>values</code>",
or have any [=inherited interfaces=]
that have [=members=] with these names.

<div class="example">

    Consider the following interface <code class="idl">SessionManager</code>, which allows access to
    a number of <code class="idl">Session</code> objects keyed by username:

    <pre highlight="webidl">
        [Exposed=Window]
        interface SessionManager {
          Session getSessionForUser(DOMString username);

          iterable&lt;DOMString, Session&gt;;
        };

        [Exposed=Window]
        interface Session {
          readonly attribute DOMString username;
          // ...
        };
    </pre>

    The behavior of the iterator could be defined like so:

    <blockquote>

        The [=value pairs to iterate over=] are the list of [=value pairs=] with the
        [=value pair/key=] being the username and the [=value pair/value=] being the open
        <code class="idl">Session</code> object on the <code class="idl">SessionManager</code>
        object corresponding to that username, sorted by username.

    </blockquote>

    In the ECMAScript language binding, the [=interface prototype object=]
    for the <code class=idl>SessionManager</code> [=interface=]
    has a <code>values</code> method that is a function, which, when invoked,
    returns an iterator object that itself has a <code>next</code> method that returns the
    next value to be iterated over.  It has <code>keys</code> and <code>entries</code>
    methods that iterate over the usernames of session objects
    and username/<code class=idl>Session</code> object pairs, respectively.  It also has
    a {{@@iterator}} method that allows a <code class="idl">SessionManager</code>
    to be used in a <code>for..of</code> loop that has the same value as the
    <code>entries</code> method:

    <pre highlight="js">
        // Get an instance of SessionManager.
        // Assume that it has sessions for two users, "anna" and "brian".
        var sm = getSessionManager();

        typeof SessionManager.prototype.values;            // Evaluates to "function"
        var it = sm.values();                              // values() returns an iterator object
<!--    String(it);                                        // Evaluates to "[object SessionManager Iterator]"
                                                           // TODO: https://github.com/heycam/webidl/issues/419 -->
        typeof it.next;                                    // Evaluates to "function"

        // This loop will log "anna" and then "brian".
        for (;;) {
          let result = it.next();
          if (result.done) {
            break;
          }
          let session = result.value;
          console.log(session.username);
        }

        // This loop will also log "anna" and then "brian".
        for (let username of sm.keys()) {
          console.log(username);
        }

        // Yet another way of accomplishing the same.
        for (let [username, session] of sm) {
          console.log(username);
        }
    </pre>
</div>

An interface must not have more than one
[=iterable declaration=].
The [=inherited interfaces=]
of an interface with an
[=iterable declaration=]
must not also have an
[=iterable declaration=].
An interface with an [=iterable declaration=]
and its [=inherited interfaces=]
must not have a
[=maplike declaration=],
[=setlike declaration=], or
[=asynchronously iterable declaration=].

The following extended attributes are applicable to [=iterable declarations=]:
[{{Exposed}}],
[{{SecureContext}}].

<pre class="grammar" id="prod-Iterable">
    Iterable :
        "iterable" "&lt;" TypeWithExtendedAttributes OptionalType "&gt;" ";"
</pre>

<pre class="grammar" id="prod-OptionalType">
    OptionalType :
        "," TypeWithExtendedAttributes
        ε
</pre>


<h4 id="idl-async-iterable">Asynchronously iterable declarations</h4>

An [=interface=] can be declared to be asynchronously iterable by using an
<dfn id="dfn-async-iterable-declaration" export>asynchronously iterable declaration</dfn>
(matching <emu-nt><a href="#prod-AsyncIterable">AsyncIterable</a></emu-nt>) in the body of the
[=interface=].

<pre highlight="webidl" class="syntax">
    interface interface_identifier {
      async iterable&lt;key_type, value_type&gt;;
    };
</pre>

Objects that [=implement=] an [=interface=] that is declared to be asynchronously iterable support
being iterated over asynchronously to obtain a sequence of values.

Note: In the ECMAScript language binding, an interface that is asynchronously iterable will have
<code class="idl">entries</code>, <code class="idl">keys</code>, <code class="idl">values</code>,
and {{@@asyncIterator}} properties on its [=interface prototype object=].

Prose accompanying an [=interface=] with an [=asynchronously iterable declaration=] must define a
<dfn id="dfn-get-the-next-iteration-result" export>get the next iteration result</dfn> algorithm.
This algorithm receives the instance of the [=interface=] that is being iterated, as well as the
async iterator itself (which can be useful for storing state).
It must return a {{Promise}} that either rejects, resolves with undefined to signal the end of the
iteration, or resolves with a tuple containing two elements:

1.  a value of the first type given in the declaration;
1.  a value of the second type given in the declaration.

The prose may also define an <dfn export>asynchronous iterator return</dfn> algorithm. This
algorithm receives the instance of the [=interface=] that is being iterated, the async iterator
itself, and a single argument value of type {{any}}. This algorithm is invoked in the case of
premature termination of the async iterator. It must return a {{Promise}}; if that promise
fulfills, its fulfillment value will be ignored, but if it rejects, that failure will be passed on
to users of the async iterator API.

<p class="note">In the ECMAScript binding, this algorithm allows customizing the behavior when the
async iterator's <code>return()</code> method is invoked. This most commonly occurs when a
<code>break</code> or <code>return</code> statement causes an exit from a
<code>for</code>-<code>await</code>-<code>of</code> loop.

<p class="note">We could add a similar hook for <code>throw()</code>. So far there has been no need,
but if you are creating an API that needs such capabilities, please
<a href="https://github.com/heycam/webidl/issues/new?title=Enhancement%20request%20for%20Async%20Iterables">file an issue</a>.

The prose may also define <dfn export>asynchronous iterator initialization steps</dfn>. These
receive the instance of the [=interface=] being iterated, as well as the newly-created
iterator object.

[=Interfaces=] with an [=asynchronously iterable declaration=] must not have any
[=interface members=] named "<code>entries</code>", "<code>keys</code>", or "<code>values</code>",
or have any [=inherited interfaces=] that have [=interface members=] with these names.

<div class="example">

    Consider the following interface <code class="idl">SessionManager</code>, which allows access
    to a number of <code class="idl">Session</code> objects keyed by username:

    <pre highlight="webidl">
        [Exposed=Window]
        interface SessionManager {
          Session getSessionForUser(DOMString username);

          async iterable&lt;DOMString, Session&gt;;
        };

        [Exposed=Window]
        interface Session {
          readonly attribute DOMString username;
          // ...
        };
    </pre>

    The behavior of the iterator could be defined like so:

    <blockquote>

        The [=asynchronous iterator initialization steps=] for a <code class="idl">SessionManager</code>
        async iterator |iterator| are:

        1.  Set |iterator|'s <dfn for="SessionManager async iterator">current state</dfn> to "not
            yet started".

        To [=get the next iteration result=] for a <code class="idl">SessionManager</code>
        |manager| and its async iterator |iterator|:

        1.  Let |promise| be a new promise.
        1.  Let |key| be the following value, if it exists, or null otherwise:
            <dl class="switch">
                  :  If |iterator|'s [=SessionManager async iterator/current state=] is "not yet
                     started"
                  :: the smallest username in |manager|'s open sessions, in lexicographical order

                  :  Otherwise
                  :: the smallest username in |manager|'s open sessions that is greater than
                     |iterator|'s current state, in lexicographical order
            </dl>

            Note: |iterator|'s [=SessionManager async iterator/current state=] might no longer be
            present in the open sessions.
        1.  If |key| is null, then:
            1.  Resolve |promise| with undefined.
        1.  Otherwise:
            1.  Let |session| be the <code class="idl">Session</code> object corresponding to |key|.
            1.  Resolve |promise| with (|username|, |session|).
            1.  Set |iterator|'s [=SessionManager async iterator/current state=] to |username|.
        1.  Return |promise|.

    </blockquote>

    In the ECMAScript language binding, the [=interface prototype object=] for the
    <code class=idl>SessionManager</code> [=interface=] has a <code>values</code> method that is a
    function, which, when invoked, returns an asynchronous iterator object that itself has a
    <code>next</code> method that returns the next value to be iterated over.
    It has <code>keys</code> and <code>entries</code> methods that iterate over the usernames of
    session objects and (username, <code class=idl>Session</code>) object pairs, respectively.
    It also has a {{@@asyncIterator}} method that allows a <code class="idl">SessionManager</code>
    to be used in a <code>for await..of</code> loop that has the same value as the
    <code>entries</code> method:

    <pre highlight="js">
        // Get an instance of SessionManager.
        // Assume that it has sessions for two users, "anna" and "brian".
        var sm = getSessionManager();

        typeof SessionManager.prototype.values;            // Evaluates to "function"
        var it = sm.values();                              // values() returns an iterator object
        typeof it.next;                                    // Evaluates to "function"

        // This loop will log "anna" and then "brian".
        for await (let username of sm.keys()) {
          console.log(username);
        }

        // Yet another way of accomplishing the same.
        for await (let [username, session] of sm) {
          console.log(username);
        }
    </pre>
</div>

An [=interface=] must not have more than one [=asynchronously iterable declaration=].
The [=inherited interfaces=] of an [=interface=] with an [=asynchronously iterable declaration=]
must not also have an [=asynchronously iterable declaration=].
An [=interface=] with an [=asynchronously iterable declaration=] and its [=inherited interfaces=]
must not have a [=maplike declaration=], [=setlike declaration=], or [=iterable declaration=].

The following extended attributes are applicable to [=asynchronously iterable declarations=]:
[{{Exposed}}],
[{{SecureContext}}].

Issue: these [=extended attributes=] are not currently taken into account.
When they are, the effect will be as you would expect.

<pre class="grammar" id="prod-AsyncIterable">
    AsyncIterable :
        "async" "iterable" "&lt;" TypeWithExtendedAttributes "," TypeWithExtendedAttributes "&gt;" ";"
</pre>


<h4 id="idl-maplike">Maplike declarations</h4>

An [=interface=] can be declared to be
<dfn id="dfn-maplike" export>maplike</dfn> by using a <dfn id="dfn-maplike-declaration" export>maplike declaration</dfn>
(matching <emu-nt><a href="#prod-ReadWriteMaplike">ReadWriteMaplike</a></emu-nt> or
<emu-t>readonly</emu-t> <emu-nt><a href="#prod-MaplikeRest">MaplikeRest</a></emu-nt>) in the body of the interface.

<pre highlight="webidl" class="syntax">
    interface interface_identifier {
      readonly maplike&lt;key_type, value_type&gt;;
      maplike&lt;key_type, value_type&gt;;
    };
</pre>

Objects implementing an interface that is declared to be maplike
represent an ordered list of key–value pairs known as its <dfn id="dfn-map-entries" export>map entries</dfn>.
The types used for the keys and values are given in the angle
brackets of the maplike declaration.  Keys are required to be unique.

The [=map entries=] of an object
implementing a [=maplike=] interface is empty at
the of the object’s creation.  Prose accompanying the interface can
describe how the [=map entries=]
of an object change.

Maplike interfaces support an API for querying the map entries
appropriate for the language binding.  If the <emu-t>readonly</emu-t>
keyword is not used, then it also supports an API for modifying
the map entries.

Note: In the ECMAScript language binding, the API for interacting
with the map entries is similar to that available on ECMAScript
{{ECMAScript/Map}} objects.  If the <emu-t>readonly</emu-t>
keyword is used, this includes <code class="idl">entries</code>,
<code class="idl">forEach</code>, <code class="idl">get</code>,
<code class="idl">has</code>, <code class="idl">keys</code>,
<code class="idl">values</code>, {{@@iterator}} methods, and a
<code class="idl">size</code> getter.
For read–write maplikes, it also includes <code class="idl">clear</code>,
<code class="idl">delete</code>, and <code class="idl">set</code> methods.

Maplike interfaces must not
have any [=interface members=]
named "<code>entries</code>", "<code>forEach</code>",
"<code>get</code>", "<code>has</code>",
"<code>keys</code>", "<code>size</code>", or
"<code>values</code>",
or have any [=inherited interfaces=]
that have [=members=] with these names.
Read–write maplike interfaces must not
have any [=attributes=]
or [=constants=] named
"<code>clear</code>", "<code>delete</code>",
or "<code>set</code>", or have any [=inherited interfaces=]
that have [=attributes=] or [=constants=] with these names.

Note: Operations named "<code>clear</code>", "<code>delete</code>",
or "<code>set</code>" are allowed on read–write maplike
interfaces and will prevent the default implementation of these methods being
added to the interface prototype object in the ECMAScript language binding.
This allows the default behavior of these operations to be overridden.

An interface must not have more than one
[=maplike declaration=].
The [=inherited interfaces=]
of a maplike interface must not
also have a [=maplike declaration=].
A maplike interface and its [=inherited interfaces=]
must not have an
[=iterable declaration=],
an [=asynchronously iterable declaration=],
a [=setlike declaration=], or
an [=indexed property getter=].

<div data-fill-with="grammar-ReadOnlyMember"></div>

<div data-fill-with="grammar-ReadOnlyMemberRest"></div>

<pre class="grammar" id="prod-ReadWriteMaplike">
    ReadWriteMaplike :
        MaplikeRest
</pre>

<pre class="grammar" id="prod-MaplikeRest">
    MaplikeRest :
        "maplike" "&lt;" TypeWithExtendedAttributes "," TypeWithExtendedAttributes "&gt;" ";"
</pre>

No [=extended attributes=]
defined in this specification are applicable to [=maplike declarations=].

<p class="issue">
    Add example.
</p>


<h4 id="idl-setlike">Setlike declarations</h4>

An [=interface=] can be declared to be
<dfn id="dfn-setlike" export>setlike</dfn> by using a <dfn id="dfn-setlike-declaration" export>setlike declaration</dfn>
(matching <emu-nt><a href="#prod-ReadWriteSetlike">ReadWriteSetlike</a></emu-nt> or
<emu-t>readonly</emu-t> <emu-nt><a href="#prod-SetlikeRest">SetlikeRest</a></emu-nt>) in the body of the interface.

<pre highlight="webidl" class="syntax">
    interface interface_identifier {
      readonly setlike&lt;type&gt;;
      setlike&lt;type&gt;;
    };
</pre>

Objects implementing an interface that is declared to be setlike
represent an ordered list of values known as its <dfn id="dfn-set-entries" export>set entries</dfn>.
The type of the values is given in the angle
brackets of the setlike declaration.  Values are required to be unique.

The [=set entries=] of an object
implementing a [=setlike=] interface is empty at
the of the object’s creation.  Prose accompanying the interface can
describe how the [=set entries=]
of an object change.

Setlike interfaces support an API for querying the set entries
appropriate for the language binding.  If the <emu-t>readonly</emu-t>
keyword is not used, then it also supports an API for modifying
the set entries.

Note: In the ECMAScript language binding, the API for interacting
with the set entries is similar to that available on ECMAScript
{{ECMAScript/Set}} objects.  If the <emu-t>readonly</emu-t>
keyword is used, this includes <code class="idl">entries</code>,
<code class="idl">forEach</code>, <code class="idl">has</code>,
<code class="idl">keys</code>, <code class="idl">values</code>,
{{@@iterator}} methods, and a <code class="idl">size</code> getter.
For read–write setlikes, it also includes <code class="idl">add</code>,
<code class="idl">clear</code>, and <code class="idl">delete</code> methods.

Setlike interfaces must not
have any [=interface members=]
named "<code>entries</code>", "<code>forEach</code>",
"<code>has</code>", "<code>keys</code>",
"<code>size</code>", or "<code>values</code>",
or have any [=inherited interfaces=]
that have [=members=] with these names.
Read–write setlike interfaces must not
have any [=attributes=]
or [=constants=] named
"<code>add</code>", "<code>clear</code>",
or "<code>delete</code>", or have any [=inherited interfaces=]
that have [=attributes=] or [=constants=] with these names.

Note: Operations named "<code>add</code>", "<code>clear</code>",
or "<code>delete</code>" are allowed on read–write setlike
interfaces and will prevent the default implementation of these methods being
added to the interface prototype object in the ECMAScript language binding.
This allows the default behavior of these operations to be overridden.

An interface must not have more than one
[=setlike declaration=].
The [=inherited interfaces=]
of a setlike interface must not
also have a [=setlike declaration=].
A setlike interface and its [=inherited interfaces=]
must not have an
[=iterable declaration=],
an [=asynchronously iterable declaration=],
a [=maplike declaration=], or
an [=indexed property getter=].

<div data-fill-with="grammar-ReadOnlyMember"></div>

<div data-fill-with="grammar-ReadOnlyMemberRest"></div>

<pre class="grammar" id="prod-ReadWriteSetlike">
    ReadWriteSetlike :
        SetlikeRest
</pre>

<pre class="grammar" id="prod-SetlikeRest">
    SetlikeRest :
        "setlike" "&lt;" TypeWithExtendedAttributes "&gt;" ";"
</pre>

No [=extended attributes=]
defined in this specification are applicable to [=setlike declarations=].

<p class="issue">
    Add example.
</p>


<h3 id="idl-namespaces">Namespaces</h3>

A <dfn id="dfn-namespace" export>namespace</dfn> is a definition (matching <emu-nt><a href="#prod-Namespace">Namespace</a></emu-nt>) that declares a global singleton with
associated behaviors.

<pre highlight="webidl" class="syntax">
    namespace identifier {
      /* namespace_members... */
    };
</pre>

A namespace is a specification of a set of
<dfn id="dfn-namespace-member" export lt="namespace member">namespace members</dfn>
(matching <emu-nt><a href="#prod-NamespaceMembers">NamespaceMembers</a></emu-nt>), which are the
[=regular operations=] and [=read only=] [=regular attributes=] that appear between the braces in
the namespace declaration. These operations and attributes describe the behaviors packaged into the
namespace.

As with interfaces, the IDL for namespaces can be split into multiple parts by using
<dfn id="dfn-partial-namespace" export>partial namespace</dfn> definitions
(matching <emu-t>partial</emu-t> <emu-nt><a href="#prod-Namespace">Namespace</a></emu-nt>). The [=identifier=] of a partial namespace definition must be the same as the identifier of a namespace definition.
All of the members that appear on each of the partial namespace definitions are
considered to be members of the namespace itself.

<pre highlight="webidl" class="syntax">
    namespace <mark>SomeNamespace</mark> {
      /* namespace_members... */
    };

    partial namespace <mark>SomeNamespace</mark> {
      /* namespace_members... */
    };
</pre>

Note: As with partial interface definitions, partial namespace definitions are intended for
use as a specification editorial aide, allowing the definition of a namespace to be
separated over more than one section of the document, and sometimes multiple
documents.

The order that members appear in has significance for property enumeration in the <a href="#es-namespaces">ECMAScript binding</a>.

Note that unlike interfaces or dictionaries, namespaces do not create types.

Of the extended attributes defined in this specification, only the [{{Exposed}}] and [{{SecureContext}}] extended attributes are applicable to namespaces.

[=Namespaces=] must be annotated with the [{{Exposed}}] [=extended attribute=].

<div data-fill-with="grammar-Partial"></div>

<div data-fill-with="grammar-PartialDefinition"></div>

<pre class="grammar" id="prod-Namespace">
    Namespace :
        "namespace" identifier "{" NamespaceMembers "}" ";"
</pre>

<pre class="grammar" id="prod-NamespaceMembers">
    NamespaceMembers :
        ExtendedAttributeList NamespaceMember NamespaceMembers
        ε
</pre>

<pre class="grammar" id="prod-NamespaceMember">
    NamespaceMember :
        RegularOperation
        "readonly" AttributeRest
</pre>

<div class="example" id="example-namespace">

    The following [=IDL fragment=] defines a
    [=namespace=].

    <pre highlight="webidl">
        namespace VectorUtils {
          readonly attribute Vector unit;
          double dotProduct(Vector x, Vector y);
          Vector crossProduct(Vector x, Vector y);
        };
    </pre>

    An ECMAScript implementation would then expose a global <code class="idl">VectorUtils</code>
    data property which was a simple object (with prototype
    {{%ObjectPrototype%}}) with enumerable data properties for each declared operation, and
    enumerable get-only accessors for each declared attribute:

    <pre highlight="js">
        Object.getPrototypeOf(VectorUtils);                         // Evaluates to Object.prototype.
        Object.keys(VectorUtils);                                   // Evaluates to ["dotProduct", "crossProduct"].
        Object.getOwnPropertyDescriptor(VectorUtils, "dotProduct"); // Evaluates to { value: &lt;a function&gt;, enumerable: true, configurable: true, writable: true }.
        Object.getOwnPropertyDescriptor(VectorUtils, "unit");       // Evaluates to { get: &lt;a function&gt;, enumerable: true, configurable: true }.
    </pre>
</div>


<h3 id="idl-dictionaries">Dictionaries</h3>

A <dfn id="dfn-dictionary" export>dictionary</dfn> is a definition (matching
<emu-nt><a href="#prod-Dictionary">Dictionary</a></emu-nt>)
used to define an [=ordered map=] data type with a fixed, ordered set of [=map/entries=],
termed <dfn id="dfn-dictionary-member" export>dictionary members</dfn>,
where [=map/keys=] are strings and [=map/values=] are of a particular type specified in the definition.

<pre highlight="webidl" class="syntax">
    dictionary identifier {
      /* dictionary_members... */
    };
</pre>

Dictionaries are always passed by value.  In language bindings where a dictionary is represented by an object of some kind, passing a
dictionary to a [=platform object=] will not result in a reference to the dictionary being kept by that object.
Similarly, any dictionary returned from a platform object will be a copy and modifications made to it will not be visible to the platform object.

A dictionary can be defined to <dfn id="dfn-inherit-dictionary" for="dictionary" export>inherit</dfn> from another dictionary.
If the identifier of the dictionary is followed by a colon and a [=identifier=],
then that identifier identifies the inherited dictionary.  The identifier
must identify a dictionary.

A dictionary must not be declared such that
its inheritance hierarchy has a cycle.  That is, a dictionary
|A| cannot inherit from itself, nor can it inherit from another
dictionary |B| that inherits from |A|, and so on.

<pre highlight="webidl" class="syntax">
    dictionary <mark>Base</mark> {
      /* dictionary_members... */
    };

    dictionary Derived : <mark>Base</mark> {
      /* dictionary_members... */
    };
</pre>

The <dfn id="dfn-inherited-dictionaries" export>inherited dictionaries</dfn> of
a given dictionary |D| is the set of all dictionaries that |D|
inherits from, directly or indirectly.  If |D| does not [=dictionary/inherit=]
from another dictionary, then the set is empty.  Otherwise, the set
includes the dictionary |E| that |D| [=interface/inherits=]
from and all of |E|’s [=inherited dictionaries=].

A dictionary value of type |D| can have key–value pairs corresponding
to the dictionary members defined on |D| and on any of |D|’s
[=inherited dictionaries=].
On a given dictionary value, the presence of each dictionary member
is optional, unless that member is specified as required.
A dictionary member is said to be
<dfn id="dfn-present" export lt="present|not present" for="dictionary member">present</dfn>
in a dictionary value if the value [=map/exists|contains an entry with the key=]
given by the member's [=identifier=], otherwise it is [=not present=].
Dictionary members can also optionally have a <dfn id="dfn-dictionary-member-default-value" for="dictionary member" export>default value</dfn>, which is
the value to use for the dictionary member when passing a value to a
[=platform object=] that does
not have a specified value.  Dictionary members with default values are
always considered to be present.

<p class="note">
    In the ECMAScript binding, a value of <emu-val>undefined</emu-val> is treated as
    [=not present=], or will trigger the [=dictionary member/default value=] where applicable.
</p>

An [=ordered map=] with string [=map/keys=] can be implicitly treated as a dictionary value of a
specific dictionary |D| if all of its [=map/entries=] correspond to [=dictionary members=], in the
correct order and with the correct types, and with appropriate [=map/entries=] for any required
dictionary members.

<div class="example">
    <pre highlight="webidl">
    dictionary Descriptor {
      DOMString name;
      sequence&lt;unsigned long> serviceIdentifiers;
    };
    </pre>

    A <code>Descriptor</code> dictionary could be created as in the following steps:

    1.  Let |identifiers| be « 1, 3, 7 ».
    1.  Return «[ "name" → "test", "serviceIdentifiers" → |identifiers| ]».
</div>

<p class="advisement">
    As with [=optional argument/default value|operation argument default values=],
    it is strongly suggested not to use <emu-val>true</emu-val> as the
    [=dictionary member/default value=] for
    {{boolean}}-typed
    [=dictionary members=],
    as this can be confusing for authors who might otherwise expect the default
    conversion of <emu-val>undefined</emu-val> to be used (i.e., <emu-val>false</emu-val>).
</p>

Each [=dictionary member=] (matching
<emu-nt><a href="#prod-DictionaryMember">DictionaryMember</a></emu-nt>) is specified
as a type (matching <emu-nt><a href="#prod-Type">Type</a></emu-nt>) followed by an
[=identifier=]
(given by an <emu-t class="regex"><a href="#prod-identifier">identifier</a></emu-t> token following
the type).  The identifier is the key name of the key–value pair.
If the <emu-nt><a href="#prod-Type">Type</a></emu-nt>
is an [=identifier=]
followed by <emu-t>?</emu-t>, then the identifier
must identify an
[=interface=], [=enumeration=],
[=callback function=], [=callback interface=] or [=typedef=].
If the dictionary member type is an identifier
not followed by <emu-t>?</emu-t>, then the identifier must
identify any one of those definitions or a [=dictionary=].

If the type of the [=dictionary member=], after resolving typedefs,
is a [=nullable type=],
its [=nullable types/inner type=] must not be a [=dictionary type=].

<pre highlight="webidl" class="syntax">
    dictionary identifier {
      type identifier;
    };
</pre>

If the identifier is followed by a <span class="char">U+003D EQUALS SIGN ("=")</span>
and a value (matching <emu-nt><a href="#prod-DefaultValue">DefaultValue</a></emu-nt>),
then that gives the dictionary member its [=dictionary member/default value=].

<pre highlight="webidl" class="syntax">
    dictionary identifier {
      type identifier = "value";
    };
</pre>

When a boolean literal token (<emu-t>true</emu-t> or <emu-t>false</emu-t>),
the <emu-t>null</emu-t> token,
an <emu-t class="regex"><a href="#prod-integer">integer</a></emu-t> token, a
<emu-t class="regex"><a href="#prod-decimal">decimal</a></emu-t> token,
one of the three special floating point literal values (<emu-t>Infinity</emu-t>,
<emu-t>-Infinity</emu-t> or <emu-t>NaN</emu-t>),
a <emu-t class="regex"><a href="#prod-string">string</a></emu-t> token, the two
token sequence <emu-t>[]</emu-t>, or the two token sequence <emu-t>{}</emu-t> is
used as the
[=dictionary member/default value=],
it is interpreted in the same way as for an [=operation=]’s
[=optional argument/default value|optional argument default value=].

If the type of the [=dictionary member=]
is an [=enumeration=], then its
[=dictionary member/default value=] if specified must
be one of the [=enumeration values|enumeration’s values=].

If the type of the dictionary member is preceded by the
<emu-t>required</emu-t> keyword, the member is considered a
<dfn id="required-dictionary-member" export>required dictionary member</dfn>
and must be present on the dictionary.

<pre highlight="webidl" class="syntax">
    dictionary identifier {
      required type identifier;
    };
</pre>

The type of a dictionary member must not include
the dictionary it appears on.  A type includes a dictionary |D|
if at least one of the following is true:

*   the type is |D|
*   the type is a dictionary that [=dictionary/inherits=] from |D|
*   the type is a [=nullable type=]
    whose [=nullable types/inner type=] includes |D|
*   the type is a [=sequence type=] or [=frozen array type|frozen array=]
    whose element type includes |D|
*   the type is a [=union type=],
    one of whose [=member types=]
    includes |D|
*   the type is a dictionary, one of whose members or inherited members has
    a type that includes |D|
*   the type is <code class="idl">[=record=]&lt;|K|, |V|></code> where |V| includes |D|

As with interfaces, the IDL for dictionaries can be split into multiple parts
by using <dfn id="dfn-partial-dictionary" export>partial dictionary</dfn> definitions
(matching <emu-t>partial</emu-t> <emu-nt><a href="#prod-Dictionary">Dictionary</a></emu-nt>).
The [=identifier=] of a partial
dictionary definition must be the same as the
identifier of a dictionary definition.  All of the members that appear on each
of the partial dictionary definitions are considered to be members of
the dictionary itself.

<pre highlight="webidl" class="syntax">
    dictionary <mark>SomeDictionary</mark> {
      /* dictionary_members... */
    };

    partial dictionary <mark>SomeDictionary</mark> {
      /* dictionary_members... */
    };
</pre>

Note: As with partial interface definitions, partial dictionary definitions are intended for use as a specification
editorial aide, allowing the definition of an interface to be separated
over more than one section of the document, and sometimes multiple documents.

The order of the [=dictionary members=]
on a given dictionary is such that inherited dictionary members are ordered
before non-inherited members, and the dictionary members on the one
dictionary definition (including any partial dictionary definitions) are
ordered lexicographically by the Unicode codepoints that comprise their
identifiers.

<div class="note">

    For example, with the following definitions:

    <pre highlight="webidl">
        dictionary B : A {
          long b;
          long a;
        };

        dictionary A {
          long c;
          long g;
        };

        dictionary C : B {
          long e;
          long f;
        };

        partial dictionary A {
          long h;
          long d;
        };
    </pre>

    the order of the [=dictionary members=]
    of a dictionary value of type <code class="idl">C</code> is
    c, d, g, h, a, b, e, f.

    Dictionaries are required to have their members ordered because
    in some language bindings the behavior observed when passing
    a dictionary value to a platform object depends on the order
    the dictionary members are fetched.  For example, consider the
    following additional interface:

    <pre highlight="webidl">
        [Exposed=Window]
        interface Something {
          void f(A a);
        };
    </pre>

    and this ECMAScript code:

    <pre highlight="js">
        var something = getSomething();  // Get an instance of Something.
        var x = 0;

        var dict = { };
        Object.defineProperty(dict, "d", { get: function() { return ++x; } });
        Object.defineProperty(dict, "c", { get: function() { return ++x; } });

        something.f(dict);
    </pre>

    The order that the dictionary members are fetched in determines
    what values they will be taken to have.  Since the order for
    <code class="idl">A</code> is defined to be c then d,
    the value for c will be 1 and the value for d will be 2.

</div>

The identifier of a dictionary member must not be
the same as that of another dictionary member defined on the dictionary or
on that dictionary’s [=inherited dictionaries=].

Dictionaries must not be used as the type of an
[=attribute=] or
[=constant=].

No [=extended attributes=] are applicable to dictionaries.

<div data-fill-with="grammar-Partial"></div>

<div data-fill-with="grammar-PartialDefinition"></div>

<pre class="grammar" id="prod-Dictionary">
    Dictionary :
        "dictionary" identifier Inheritance "{" DictionaryMembers "}" ";"
</pre>

<pre class="grammar" id="prod-DictionaryMembers">
    DictionaryMembers :
        DictionaryMember DictionaryMembers
        ε
</pre>

<pre class="grammar" id="prod-DictionaryMember">
    DictionaryMember :
        ExtendedAttributeList DictionaryMemberRest
</pre>

<pre class="grammar" id="prod-DictionaryMemberRest">
    DictionaryMemberRest :
        "required" TypeWithExtendedAttributes identifier ";"
        Type identifier Default ";"
</pre>

<pre class="grammar" id="prod-PartialDictionary">
    PartialDictionary :
        "dictionary" identifier "{" DictionaryMembers "}" ";"
</pre>

<pre class="grammar" id="prod-Default">
    Default :
        "=" DefaultValue
        ε
</pre>

<div data-fill-with="grammar-DefaultValue"></div>

<div data-fill-with="grammar-Inheritance"></div>

<div class="example">

    One use of dictionary types is to allow a number of optional arguments to
    an [=operation=] without being
    constrained as to the order they are specified at the call site.  For example,
    consider the following [=IDL fragment=]:

    <pre highlight="webidl">
        [Exposed=Window]
        interface Point {
          constructor();
          attribute double x;
          attribute double y;
        };

        dictionary PaintOptions {
          DOMString? fillPattern = "black";
          DOMString? strokePattern = null;
          Point position;
        };

        [Exposed=Window]
        interface GraphicsContext {
          void drawRectangle(double width, double height, optional PaintOptions options);
        };
    </pre>

    In an ECMAScript implementation of the IDL, an Object
    can be passed in for the optional <code class="idl">PaintOptions</code> dictionary:

    <pre highlight="js">
        // Get an instance of GraphicsContext.
        var ctx = getGraphicsContext();

        // Draw a rectangle.
        ctx.drawRectangle(300, 200, { fillPattern: "red", position: new Point(10, 10) });
    </pre>

    Both fillPattern and strokePattern are given [=dictionary member/default values=],
    so if they are omitted, the definition of drawRectangle can assume that they
    have the given default values and not include explicit wording to handle
    their non-presence.

</div>


<h3 id="idl-exceptions">Exceptions</h3>

An <dfn id="dfn-exception" export>exception</dfn> is a type of object that
represents an error and which can be thrown or treated as a first
class value by implementations.  Web IDL does not allow exceptions
to be defined, but instead has a number of pre-defined exceptions
that specifications can reference and throw in their definition of
operations, attributes, and so on.  Exceptions have an
<dfn id="dfn-exception-error-name" for="exception" export>error name</dfn>,
a {{DOMString}},
which is the type of error the exception represents, and a
<dfn id="dfn-exception-message" for="exception" export>message</dfn>, which is an optional,
user agent-defined value that provides human readable details of the error.

There are two kinds of exceptions available to be thrown from specifications.
The first is a <dfn id="dfn-simple-exception" export>simple exception</dfn>, which
is identified by one of the following types:

*   <dfn exception>EvalError</dfn>
*   <dfn exception>RangeError</dfn>
*   <dfn exception>ReferenceError</dfn>
*   <dfn exception>TypeError</dfn>
*   <dfn exception>URIError</dfn>

These correspond to all of the ECMAScript [=ECMAScript/error objects=]
(apart from {{ECMAScript/SyntaxError}} and {{ECMAScript/Error}},
which are deliberately omitted as they are reserved for use
by the ECMAScript parser and by authors, respectively).
The meaning of each [=simple exception=] matches
its corresponding error object in the
ECMAScript specification.

The second kind of exception is a {{DOMException}},
which is an exception that encapsulates a name and an optional integer code,
for compatibility with historically defined exceptions in the DOM.

For [=simple exceptions=], the [=error name=] is the type of the exception.
For a {{DOMException}}, the [=error name=] must be one of the names
listed in the [=error names table=] below.
The table also indicates the {{DOMException}}'s integer code for that error name,
if it has one.

Note: As {{DOMException}} is an [=interface type=], it can be used as a type in IDL.
This allows for example an [=operation=]
to be declared to have a {{DOMException}}
[=return type=].

[=Simple exceptions=] can be <dfn id="dfn-create-exception" for="exception" export>created</dfn>
by providing their [=error name=].
A {{DOMException}} can be [=created=]
by providing its [=error name=] followed by {{DOMException}}.
Exceptions can also be <dfn id="dfn-throw" for="exception" export lt="throw">thrown</dfn>, by providing the
same details required to [=created|create=] one.

The resulting behavior from creating and throwing an exception is language binding-specific.

Note: See [[#es-creating-throwing-exceptions]] for details on what creating and throwing an exception
entails in the ECMAScript language binding.

<div class="example">

    Here is are some examples of wording to use to create and throw exceptions.
    To throw a new [=simple exception=] named {{TypeError}}:

    <blockquote>
        [=exception/Throw=] a {{TypeError}}.
    </blockquote>

    To throw a new {{DOMException}} with [=error name=] "{{NotAllowedError!!exception}}":

    <blockquote>
        [=exception/Throw=] an "{{NotAllowedError!!exception}}" {{DOMException}}.
    </blockquote>

    To create a new {{DOMException}} with [=error name=] "{{SyntaxError!!exception}}":

    <blockquote>
        Let <var ignore>object</var> be a newly [=created=] "{{SyntaxError!!exception}}" {{DOMException}}.
    </blockquote>
</div>


<h4 id="idl-DOMException-error-names">Error names</h4>

The <dfn id="dfn-error-names-table" export>error names table</dfn> below lists all the allowed error names
for {{DOMException}}, a description, and legacy code values.

<p class="advisement">
    The {{DOMException}} names marked as deprecated are kept for legacy purposes but their usage is discouraged.
</p>

Note: If an error name is not listed here, please file a bug as indicated at the top of this specification and it will be addressed shortly. Thanks!

Note: Don't confuse the "{{SyntaxError!!exception}}" {{DOMException}} defined here
with ECMAScript's {{ECMAScript/SyntaxError}}.
"{{SyntaxError!!exception}}" {{DOMException}} is used to report parsing errors in web APIs,
for example when parsing selectors,
while the ECMAScript {{ECMAScript/SyntaxError}} is reserved for the ECMAScript parser.
To help disambiguate this further,
always favor the "{{SyntaxError!!exception}}" {{DOMException}} notation
over just using {{SyntaxError!!exception}} to refer to the {{DOMException}}. [[DOM]]

<table id="error-names" class="vert data">
    <thead>
        <tr><th>Name</th><th>Description</th><th>Legacy code name and value</th></tr>
    </thead>
    <tbody>
        <tr class="deprecated">
            <td>"<dfn id="indexsizeerror" exception export><code>IndexSizeError</code></dfn>"</td>
            <td><strong>Deprecated.</strong> Use {{RangeError}} instead.</td></td>
            <td><dfn id="dom-domexception-index_size_err" for="DOMException" const export><code>INDEX_SIZE_ERR</code></dfn>&nbsp;(1)</td>
        </tr>
        <tr class="deprecated">
            <td>"<dfn id="domstringsizeerror" exception export><code>DOMStringSizeError</code></dfn>"</td>
            <td><strong>Deprecated.</strong> Use {{RangeError}} instead.</td>
            <td><dfn id="dom-domexception-domstring_size_err" for="DOMException" const><code>DOMSTRING_SIZE_ERR</code></dfn>&nbsp;(2)</td>
        </tr>
        <tr>
            <td>"<dfn id="hierarchyrequesterror" exception export><code>HierarchyRequestError</code></dfn>"</td>
            <td>The operation would yield an incorrect [=node tree=]. [[!DOM]]</td>
            <td><dfn id="dom-domexception-hierarchy_request_err" for="DOMException" const export><code>HIERARCHY_REQUEST_ERR</code></dfn>&nbsp;(3)</td>
        </tr>
        <tr>
            <td>"<dfn id="wrongdocumenterror" exception export><code>WrongDocumentError</code></dfn>"</td>
            <td>The object is in the wrong [=document=]. [[!DOM]]</td>
            <td><dfn id="dom-domexception-wrong_document_err" for="DOMException" const export><code>WRONG_DOCUMENT_ERR</code></dfn>&nbsp;(4)</td>
        </tr>
        <tr>
            <td>"<dfn id="invalidcharactererror" exception export><code>InvalidCharacterError</code></dfn>"</td>
            <td>The string contains invalid characters.</td>
            <td><dfn id="dom-domexception-invalid_character_err" for="DOMException" const export><code>INVALID_CHARACTER_ERR</code></dfn>&nbsp;(5)</td>
        </tr>
        <tr class="deprecated">
            <td>"<dfn id="nodataallowederror" exception export><code>NoDataAllowedError</code></dfn>"</td>
            <td><strong>Deprecated.</strong></td>
            <td><dfn id="dom-domexception-no_data_allowed_err" for="DOMException" const><code>NO_DATA_ALLOWED_ERR</code></dfn>&nbsp;(6)</td>
        </tr>
        <tr>
            <td>"<dfn id="nomodificationallowederror" exception export><code>NoModificationAllowedError</code></dfn>"</td>
            <td>The object can not be modified.</td>
            <td><dfn id="dom-domexception-no_modification_allowed_err" for="DOMException" const export><code>NO_MODIFICATION_ALLOWED_ERR</code></dfn>&nbsp;(7)</td>
        </tr>
        <tr>
            <td>"<dfn id="notfounderror" exception export><code>NotFoundError</code></dfn>"</td>
            <td>The object can not be found here.</td>
            <td><dfn id="dom-domexception-not_found_err" for="DOMException" const export><code>NOT_FOUND_ERR</code></dfn>&nbsp;(8)</td>
        </tr>
        <tr>
            <td>"<dfn id="notsupportederror" exception export><code>NotSupportedError</code></dfn>"</td>
            <td>The operation is not supported.</td>
            <td><dfn id="dom-domexception-not_supported_err" for="DOMException" const export><code>NOT_SUPPORTED_ERR</code></dfn>&nbsp;(9)</td>
        </tr>
        <tr>
            <td>"<dfn id="inuseattributeerror" exception export><code>InUseAttributeError</code></dfn>"</td>
            <td>The attribute is in use.</td>
            <td><dfn id="dom-domexception-inuse_attribute_err" for="DOMException" const export><code>INUSE_ATTRIBUTE_ERR</code></dfn>&nbsp;(10)</td>
        </tr>
        <tr>
            <td>"<dfn id="invalidstateerror" exception export><code>InvalidStateError</code></dfn>"</td>
            <td>The object is in an invalid state.</td>
            <td><dfn id="dom-domexception-invalid_state_err" for="DOMException" const export><code>INVALID_STATE_ERR</code></dfn>&nbsp;(11)</td>
        </tr>
        <tr>
            <td>"<dfn id="syntaxerror" exception export><code>SyntaxError</code></dfn>"</td>
            <td>The string did not match the expected pattern.</td>
            <td><dfn id="dom-domexception-syntax_err" for="DOMException" const export><code>SYNTAX_ERR</code></dfn>&nbsp;(12)</td>
        </tr>
        <tr>
            <td>"<dfn id="invalidmodificationerror" exception export><code>InvalidModificationError</code></dfn>"</td>
            <td>The object can not be modified in this way.</td>
            <td><dfn id="dom-domexception-invalid_modification_err" for="DOMException" const export><code>INVALID_MODIFICATION_ERR</code></dfn>&nbsp;(13)</td>
        </tr>
        <tr>
            <td>"<dfn id="namespaceerror" exception export><code>NamespaceError</code></dfn>"</td>
            <td>The operation is not allowed by <cite>Namespaces in XML</cite>. [[XML-NAMES]]</td>
            <td><dfn id="dom-domexception-namespace_err" for="DOMException" const export><code>NAMESPACE_ERR</code></dfn>&nbsp;(14)</td>
        </tr>
        <tr class="deprecated">
            <td>"<dfn id="invalidaccesserror" exception export><code>InvalidAccessError</code></dfn>"</td>
            <td>
                <strong>Deprecated.</strong>
                Use {{TypeError}} for invalid arguments,
                "{{NotSupportedError!!exception}}" {{DOMException}} for unsupported operations, and
                "{{NotAllowedError!!exception}}" {{DOMException}} for denied requests instead.
            </td>
            <td><dfn id="dom-domexception-invalid_access_err" for="DOMException" const><code>INVALID_ACCESS_ERR</code></dfn>&nbsp;(15)</td>
        </tr>
        <tr class="deprecated">
            <td>"<dfn id="validationerror" exception export><code>ValidationError</code></dfn>"</td>
            <td><strong>Deprecated.</strong></td>
            <td><dfn id="dom-domexception-validation_err" for="DOMException" const><code>VALIDATION_ERR</code></dfn>&nbsp;(16)</td>
        </tr>
        <tr class="deprecated">
            <td>"<dfn id="typemismatcherror" exception export><code>TypeMismatchError</code></dfn>"</td>
            <td><strong>Deprecated.</strong> Use {{TypeError}} instead.</td>
            <td><dfn id="dom-domexception-type_mismatch_err" for="DOMException" const><code>TYPE_MISMATCH_ERR</code></dfn>&nbsp;(17)</td>
        </tr>
        <tr>
            <td>"<dfn id="securityerror" exception export><code>SecurityError</code></dfn>"</td>
            <td>The operation is insecure.</td>
            <td><dfn id="dom-domexception-security_err" for="DOMException" const export><code>SECURITY_ERR</code></dfn>&nbsp;(18)</td>
        </tr>
        <tr>
            <td>"<dfn id="networkerror" exception export><code>NetworkError</code></dfn>"</td>
            <td>A network error occurred.</td>
            <td><dfn id="dom-domexception-network_err" for="DOMException" const export><code>NETWORK_ERR</code></dfn>&nbsp;(19)</td>
        </tr>
        <tr>
            <td>"<dfn id="aborterror" exception export><code>AbortError</code></dfn>"</td>
            <td>The operation was aborted.</td>
            <td><dfn id="dom-domexception-abort_err" for="DOMException" const export><code>ABORT_ERR</code></dfn>&nbsp;(20)</td>
        </tr>
        <tr>
            <td>"<dfn id="urlmismatcherror" exception export><code>URLMismatchError</code></dfn>"</td>
            <td>The given URL does not match another URL.</td>
            <td><dfn id="dom-domexception-url_mismatch_err" for="DOMException" const export><code>URL_MISMATCH_ERR</code></dfn>&nbsp;(21)</td>
        </tr>
        <tr>
            <td>"<dfn id="quotaexceedederror" exception export><code>QuotaExceededError</code></dfn>"</td>
            <td>The quota has been exceeded.</td>
            <td><dfn id="dom-domexception-quota_exceeded_err" for="DOMException" const export><code>QUOTA_EXCEEDED_ERR</code></dfn>&nbsp;(22)</td>
        </tr>
        <tr>
            <td>"<dfn id="timeouterror" exception export><code>TimeoutError</code></dfn>"</td>
            <td>The operation timed out.</td>
            <td><dfn id="dom-domexception-timeout_err" for="DOMException" const export><code>TIMEOUT_ERR</code></dfn>&nbsp;(23)</td>
        </tr>
        <tr>
            <td>"<dfn id="invalidnodetypeerror" exception export><code>InvalidNodeTypeError</code></dfn>"</td>
            <td>The supplied node is incorrect or has an incorrect ancestor for this operation.</td>
            <td><dfn id="dom-domexception-invalid_node_type_err" for="DOMException" const export><code>INVALID_NODE_TYPE_ERR</code></dfn>&nbsp;(24)</td>
        </tr>
        <tr>
            <td>"<dfn id="datacloneerror" exception export><code>DataCloneError</code></dfn>"</td>
            <td>The object can not be cloned.</td>
            <td><dfn id="dom-domexception-data_clone_err" for="DOMException" const export><code>DATA_CLONE_ERR</code></dfn>&nbsp;(25)</td>
        </tr>
        <tr>
            <td>"<dfn id="encodingerror" exception export><code>EncodingError</code></dfn>"</td>
            <td>The encoding operation (either encoded or decoding) failed.</td>
            <td>—</td>
        </tr>
        <tr>
            <td>"<dfn id="notreadableerror" exception export><code>NotReadableError</code></dfn>"</td>
            <td>The I/O read operation failed.</td>
            <td>—</td>
        </tr>
        <tr>
            <td>"<dfn id="unknownerror" exception export><code>UnknownError</code></dfn>"</td>
            <td>The operation failed for an unknown transient reason (e.g. out of memory).</td>
            <td>—</td>
        </tr>
        <tr>
            <td>"<dfn id="constrainterror" exception export><code>ConstraintError</code></dfn>"</td>
            <td>A mutation operation in a transaction failed because a constraint was not satisfied.</td>
            <td>—</td>
        </tr>
        <tr>
            <td>"<dfn id="dataerror" exception export><code>DataError</code></dfn>"</td>
            <td>Provided data is inadequate.</td>
            <td>—</td>
        </tr>
        <tr>
            <td>"<dfn id="transactioninactiveerror" exception export><code>TransactionInactiveError</code></dfn>"</td>
            <td>A request was placed against a transaction which is currently not active, or which is finished.</td>
            <td>—</td>
        </tr>
        <tr>
            <td>"<dfn id="readonlyerror" exception export><code>ReadOnlyError</code></dfn>"</td>
            <td>The mutating operation was attempted in a "readonly" transaction.</td>
            <td>—</td>
        </tr>
        <tr>
            <td>"<dfn id="versionerror" exception export><code>VersionError</code></dfn>"</td>
            <td>An attempt was made to open a database using a lower version than the existing version.</td>
            <td>—</td>
        </tr>
        <tr>
            <td>"<dfn id="operationerror" exception export><code>OperationError</code></dfn>"</td>
            <td>The operation failed for an operation-specific reason.</td>
            <td>—</td>
        </tr>
        <tr>
            <td>"<dfn id="notallowederror" exception export><code>NotAllowedError</code></dfn>"</td>
            <td>The request is not allowed by the user agent or the platform in the current context, possibly because the user denied permission.</td>
            <td>—</td>
        </tr>
    </tbody>
</table>


<h3 id="idl-enums">Enumerations</h3>

An <dfn id="dfn-enumeration" export>enumeration</dfn> is a definition (matching
<emu-nt><a href="#prod-Enum">Enum</a></emu-nt>) used to declare a type
whose valid values are a set of predefined strings.  Enumerations
can be used to restrict the possible
{{DOMString}} values that can be assigned to an
[=attribute=] or passed to an
[=operation=].

<pre highlight="webidl" class="syntax">enum identifier { "enum", "values" /* , ... */ };</pre>

The <dfn id="dfn-enumeration-value" export lt="enumeration value">enumeration values</dfn> are specified
as a comma-separated list of <emu-t class="regex"><a href="#prod-string">string</a></emu-t> literals.
The list of [=enumeration values=]
must not include duplicates.

<p class="advisement">
    It is strongly suggested that enumeration values be all lowercase,
    and that multiple words be separated using dashes or not be
    separated at all, unless there is a specific reason to use another
    value naming scheme.  For example, an enumeration value that
    indicates an object should be created could be named
    "<code>createobject</code>" or "<code>create-object</code>".
    Consider related uses of enumeration values when deciding whether
    to dash-separate or not separate enumeration value words so that
    similar APIs are consistent.
</p>

The behavior when a string value that is not one a valid enumeration value
is used when assigning to an [=attribute=],
or passed as an [=operation=] argument,
whose type is the enumeration, is language binding specific.

Note: In the ECMAScript binding, assignment of an invalid string value to an
[=attribute=] is ignored, while
passing such a value in other contexts (for example as an [=operation=] argument)
results in an exception being thrown.

No [=extended attributes=]
defined in this specification are applicable to [=enumerations=].

<pre class="grammar" id="prod-Enum">
    Enum :
        "enum" identifier "{" EnumValueList "}" ";"
</pre>

<pre class="grammar" id="prod-EnumValueList">
    EnumValueList :
        string EnumValueListComma
</pre>

<pre class="grammar" id="prod-EnumValueListComma">
    EnumValueListComma :
        "," EnumValueListString
        ε
</pre>

<pre class="grammar" id="prod-EnumValueListString">
    EnumValueListString :
        string EnumValueListComma
        ε
</pre>

<div class="example">

    The following [=IDL fragment=]
    defines an [=enumeration=]
    that is used as the type of an [=attribute=]
    and an [=operation=] argument:

    <pre highlight="webidl">
        enum MealType { "rice", "noodles", "other" };

        [Exposed=Window]
        interface Meal {
          attribute MealType type;
          attribute double size;     // in grams

          void initialize(MealType type, double size);
        };
    </pre>

    An ECMAScript implementation would restrict the strings that can be
    assigned to the type property or passed to the initializeMeal function
    to those identified in the [=enumeration=].

    <pre highlight="js">
        var meal = getMeal();                // Get an instance of Meal.

        meal.initialize("rice", 200);        // Operation invoked as normal.

        try {
          meal.initialize("sandwich", 100);  // Throws a TypeError.
        } catch (e) {
        }

        meal.type = "noodles";               // Attribute assigned as normal.
        meal.type = "dumplings";             // Attribute assignment ignored.
        meal.type == "noodles";              // Evaluates to true.
    </pre>
</div>


<h3 id="idl-callback-functions">Callback functions</h3>

<p class="issue">
    The “Custom DOM Elements” spec wants to use callback function types for
    platform object provided functions.  Should we rename “callback functions” to
    just “functions” to make it clear that they can be used for both purposes?
</p>

A <dfn id="dfn-callback-function" export>callback function</dfn> is a definition (matching
<emu-t>callback</emu-t> <emu-nt><a href="#prod-CallbackRest">CallbackRest</a></emu-nt>) used to declare a function type.

<pre highlight="webidl" class="syntax">callback identifier = return_type (/* arguments... */);</pre>

Note: See also the similarly named [=callback interfaces=].

The [=identifier=] on the
left of the equals sign gives the name of the [=callback function=]
and the return type and argument list (matching <emu-nt><a href="#prod-ReturnType">ReturnType</a></emu-nt>
and <emu-nt><a href="#prod-ArgumentList">ArgumentList</a></emu-nt>) on the right side of the equals
sign gives the signature of the callback function type.

[=Callback functions=] must not
be used as the type of a [=constant=].

The following extended attribute is applicable to callback functions:
[{{TreatNonObjectAsNull}}].

<div data-fill-with="grammar-CallbackOrInterfaceOrMixin"></div>

<div data-fill-with="grammar-CallbackRestOrInterfaceOrMixin"></div>

<pre class="grammar" id="prod-CallbackRest">
    CallbackRest :
        identifier "=" ReturnType "(" ArgumentList ")" ";"
</pre>

<div class="example">

    The following [=IDL fragment=] defines
    a [=callback function=] used for an API that
    invokes a user-defined function when an operation is complete.

    <pre highlight="webidl">
        callback AsyncOperationCallback = void (DOMString status);

        [Exposed=Window]
        interface AsyncOperations {
          void performOperation(AsyncOperationCallback whenFinished);
        };
    </pre>

    In the ECMAScript language binding, a [=function object=] is
    passed as the operation argument.

    <pre highlight="js">
        var ops = getAsyncOperations();  // Get an instance of AsyncOperations.

        ops.performOperation(function(status) {
          window.alert("Operation finished, status is " + status + ".");
        });
    </pre>
</div>


<h3 id="idl-typedefs">Typedefs</h3>

A <dfn id="dfn-typedef" export>typedef</dfn> is a definition (matching
<emu-nt><a href="#prod-Typedef">Typedef</a></emu-nt>)
used to declare a new name for a type.  This new name is not exposed
by language bindings; it is purely used as a shorthand for referencing
the type in the IDL.

<pre highlight="webidl" class="syntax">typedef type identifier;</pre>

The <dfn>type being given a new name</dfn> is specified after the <emu-t>typedef</emu-t>
keyword (matching <emu-nt><a href="#prod-Type">TypeWithExtendedAttributes</a></emu-nt>), and the
<emu-t class="regex"><a href="#prod-identifier">identifier</a></emu-t> token following the
type gives the name.

The <emu-nt><a href="#prod-Type">Type</a></emu-nt> must not
be the identifier of the same or another [=typedef=].

No [=extended attributes=]
defined in this specification are applicable to [=typedefs=].

<pre class="grammar" id="prod-Typedef">
    Typedef :
        "typedef" TypeWithExtendedAttributes identifier ";"
</pre>

<div class="example">

    The following [=IDL fragment=]
    demonstrates the use of [=typedefs=]
    to allow the use of a short
    [=identifier=] instead of a long
    [=sequence type=].

    <pre highlight="webidl">
        [Exposed=Window]
        interface Point {
          attribute double x;
          attribute double y;
        };

        typedef sequence&lt;Point&gt; Points;

        [Exposed=Window]
        interface Widget {
          boolean pointWithinBounds(Point p);
          boolean allPointsWithinBounds(Points ps);
        };
    </pre>
</div>


<h3 id="idl-objects">Objects implementing interfaces</h3>

In a given implementation of a set of [=IDL fragments=],
an object can be described as being a [=platform object=].

<dfn id="dfn-platform-object" lt="platform object" export>Platform objects</dfn> are objects
that implement an [=interface=].

<dfn id="dfn-legacy-platform-object" export>Legacy platform objects</dfn> are
[=platform objects=] that implement an [=interface=] which
does not have a [{{Global}}] [=extended attribute=], and which
[=support indexed properties|supports indexed properties=],
[=support named properties|named properties=], or both.

In a browser, for example,
the browser-implemented DOM objects (implementing interfaces such as <code class="idl">Node</code> and
<code class="idl">Document</code>) that provide access to a web page’s contents
to ECMAScript running in the page would be [=platform objects=].  These objects might be exotic objects,
implemented in a language like C++, or they might be native ECMAScript objects.  Regardless,
an implementation of a given set of IDL fragments needs to be able to recognize all [=platform objects=]
that are created by the implementation.  This might be done by having some internal state that records whether
a given object is indeed a platform object for that implementation, or perhaps by observing
that the object is implemented by a given internal C++ class.  How exactly platform objects
are recognized by a given implementation of a set of IDL fragments is implementation specific.

All other objects in the system would not be treated as platform objects.  For example, assume that
a web page opened in a browser loads an ECMAScript library that implements DOM Core.  This library
would be considered to be a different implementation from the browser provided implementation.
The objects created by the ECMAScript library that implement the <code class="idl">Node</code> interface
will not be treated as platform objects that implement <code class="idl">Node</code> by the browser implementation.

[=Callback interfaces=], on the other hand, can be implemented by any ECMAScript object. This
allows Web APIs to invoke author-defined operations. For example, the DOM Events implementation
allows authors to register callbacks by providing objects that implement the
{{EventListener}} interface.


<h3 id="idl-types">Types</h3>

This section lists the types supported by Web IDL, the set of values
corresponding to each type, and how [=constants=]
of that type are represented.

The following types are known as <dfn id="dfn-integer-type" export>integer types</dfn>:
{{byte}},
{{octet}},
{{short}},
{{unsigned short}},
{{long}},
{{unsigned long}},
{{long long}} and
{{unsigned long long}}.

The following types are known as <dfn id="dfn-numeric-type" export>numeric types</dfn>:
the [=integer types=],
{{float}},
{{unrestricted float}},
{{double}} and
{{unrestricted double}}.

The <dfn id="dfn-primitive-type" export>primitive types</dfn> are
{{boolean}} and the [=numeric types=].

The <dfn id="dfn-string-type" export>string types</dfn> are
{{DOMString}}, all [=enumeration types=],
{{ByteString}} and {{USVString}}.

The <dfn id="dfn-typed-array-type" export>typed array types</dfn> are
{{Int8Array}},
{{Int16Array}},
{{Int32Array}},
{{Uint8Array}},
{{Uint16Array}},
{{Uint32Array}},
{{Uint8ClampedArray}},
{{Float32Array}} and
{{Float64Array}}.

The <dfn id="dfn-buffer-source-type" export>buffer source types</dfn>
are {{ArrayBuffer}},
{{DataView}},
and the [=typed array types=].

The {{object}} type,
all [=interface types=], and
all [=callback interface types=]
are known as <dfn id="dfn-object-type" export>object types</dfn>.

Every type has a <dfn id="dfn-type-name" export>type name</dfn>, which
is a string, not necessarily unique, that identifies the type.
Each sub-section below defines what the type name is for each
type.

<p id="type-conversion-exceptions">
    When conversions are made from language binding specific types to
    IDL types in order to invoke an [=operation=]
    or assign a value to an [=attribute=],
    all conversions necessary will be performed before the
    specified functionality of the operation or attribute assignment
    is carried out.  If the conversion cannot
    be performed, then the operation will not run or
    the attribute will not be updated.  In some language bindings,
    type conversions could result in an exception being thrown.
    In such cases, these exceptions will be propagated to the
    code that made the attempt to invoke the operation or
    assign to the attribute.
</p>

<pre class="grammar" id="prod-Type">
    Type :
        SingleType
        UnionType Null
</pre>

<pre class="grammar" id="prod-TypeWithExtendedAttributes">
    TypeWithExtendedAttributes :
        ExtendedAttributeList Type
</pre>

<pre class="grammar" id="prod-SingleType">
    SingleType :
        DistinguishableType
        "any"
        PromiseType
</pre>

<pre class="grammar" id="prod-UnionType">
    UnionType :
        "(" UnionMemberType "or" UnionMemberType UnionMemberTypes ")"
</pre>

<pre class="grammar" id="prod-UnionMemberType">
    UnionMemberType :
        ExtendedAttributeList DistinguishableType
        UnionType Null
</pre>

<pre class="grammar" id="prod-UnionMemberTypes">
    UnionMemberTypes :
        "or" UnionMemberType UnionMemberTypes
        ε
</pre>

<pre class="grammar" id="prod-DistinguishableType">
    DistinguishableType :
        PrimitiveType Null
        StringType Null
        identifier Null
        "sequence" "&lt;" TypeWithExtendedAttributes "&gt;" Null
        "object" Null
        "symbol" Null
        BufferRelatedType Null
        "FrozenArray" "&lt;" TypeWithExtendedAttributes "&gt;" Null
        RecordType Null
</pre>

<div data-fill-with="grammar-ConstType"></div>

<pre class="grammar" id="prod-PrimitiveType">
    PrimitiveType :
        UnsignedIntegerType
        UnrestrictedFloatType
        "boolean"
        "byte"
        "octet"
</pre>

<pre class="grammar" id="prod-UnrestrictedFloatType">
    UnrestrictedFloatType :
        "unrestricted" FloatType
        FloatType
</pre>

<pre class="grammar" id="prod-FloatType">
    FloatType :
        "float"
        "double"
</pre>

<pre class="grammar" id="prod-UnsignedIntegerType">
    UnsignedIntegerType :
        "unsigned" IntegerType
        IntegerType
</pre>

<pre class="grammar" id="prod-IntegerType">
    IntegerType :
        "short"
        "long" OptionalLong
</pre>

<pre class="grammar" id="prod-OptionalLong">
    OptionalLong :
        "long"
        ε
</pre>

<pre class="grammar" id="prod-StringType">
    StringType :
        "ByteString"
        "DOMString"
        "USVString"
</pre>

<pre class="grammar" id="prod-PromiseType">
    PromiseType :
        "Promise" "&lt;" ReturnType "&gt;"
</pre>

<pre class="grammar" id="prod-RecordType">
    RecordType :
        "record" "&lt;" StringType "," TypeWithExtendedAttributes "&gt;"
</pre>

<pre class="grammar" id="prod-Null">
    Null :
        "?"
        ε
</pre>

<h4 oldids="dom-any" id="idl-any" interface>any</h4>

The {{any}} type is the union of all other possible
non-[=union type|union=] types.
Its [=type name=] is "<code>Any</code>".

The {{any}} type is like
a discriminated union type, in that each of its values has a
specific non-{{any}} type
associated with it.  For example, one value of the
{{any}} type is the
{{unsigned long}}
150, while another is the {{long}} 150.
These are distinct values.

The particular type of an {{any}}
value is known as its <dfn id="dfn-specific-type" export>specific type</dfn>.
(Values of [=union types=] also have
[=specific types=].)

<h4 id="idl-void" interface>void</h4>

The {{void}} type has a unique value.

It can only be used as the [=return type=] of an [=operation=] or the parameter of a
[=promise type=].

The [=type name=] of the {{void}} type is "<code>Void</code>".


<h4 oldids="dom-boolean" id="idl-boolean" interface>boolean</h4>

The {{boolean}} type has two values:
<code class="idl">true</code> and <code class="idl">false</code>.

{{boolean}} constant values in IDL are
represented with the <emu-t>true</emu-t> and
<emu-t>false</emu-t> tokens.

The [=type name=] of the
{{boolean}} type is "<code>Boolean</code>".


<h4 oldids="dom-byte" id="idl-byte" interface>byte</h4>

The {{byte}} type is a signed integer
type that has values in the range [−128, 127].

{{byte}} constant values in IDL are
represented with <emu-t class="regex"><a href="#prod-integer">integer</a></emu-t>
tokens.

The [=type name=] of the
{{byte}} type is "<code>Byte</code>".


<h4 oldids="dom-octet" id="idl-octet" interface>octet</h4>

The {{octet}} type is an unsigned integer
type that has values in the range [0, 255].

{{octet}} constant values in IDL are
represented with <emu-t class="regex"><a href="#prod-integer">integer</a></emu-t>
tokens.

The [=type name=] of the
{{octet}} type is "<code>Octet</code>".


<h4 oldids="dom-short" id="idl-short" interface>short</h4>

The {{short}} type is a signed integer
type that has values in the range [−32768, 32767].

{{short}} constant values in IDL are
represented with <emu-t class="regex"><a href="#prod-integer">integer</a></emu-t>
tokens.

The [=type name=] of the
{{short}} type is "<code>Short</code>".


<h4 oldids="dom-unsignedshort" id="idl-unsigned-short" interface>unsigned short</h4>

The {{unsigned short}} type is an unsigned integer
type that has values in the range [0, 65535].

{{unsigned short}} constant values in IDL are
represented with <emu-t class="regex"><a href="#prod-integer">integer</a></emu-t>
tokens.

The [=type name=] of the
{{unsigned short}} type is "<code>UnsignedShort</code>".


<h4 oldids="dom-long" id="idl-long" interface>long</h4>

The {{long}} type is a signed integer
type that has values in the range [−2147483648, 2147483647].

{{long}} constant values in IDL are
represented with <emu-t class="regex"><a href="#prod-integer">integer</a></emu-t>
tokens.

The [=type name=] of the
{{long}} type is "<code>Long</code>".


<h4 oldids="dom-unsignedlong" id="idl-unsigned-long" interface>unsigned long</h4>

The {{unsigned long}} type is an unsigned integer
type that has values in the range [0, 4294967295].

{{unsigned long}} constant values in IDL are
represented with <emu-t class="regex"><a href="#prod-integer">integer</a></emu-t>
tokens.

The [=type name=] of the
{{unsigned long}} type is "<code>UnsignedLong</code>".


<h4 oldids="dom-longlong" id="idl-long-long" interface>long long</h4>

The {{long long}} type is a signed integer
type that has values in the range [−9223372036854775808, 9223372036854775807].

{{long long}} constant values in IDL are
represented with <emu-t class="regex"><a href="#prod-integer">integer</a></emu-t>
tokens.

The [=type name=] of the
{{long long}} type is "<code>LongLong</code>".


<h4 oldids="dom-unsignedlonglong" id="idl-unsigned-long-long" interface>unsigned long long</h4>

The {{unsigned long long}} type is an unsigned integer
type that has values in the range [0, 18446744073709551615].

{{unsigned long long}} constant values in IDL are
represented with <emu-t class="regex"><a href="#prod-integer">integer</a></emu-t>
tokens.

The [=type name=] of the
{{unsigned long long}} type is "<code>UnsignedLongLong</code>".


<h4 oldids="dom-float" id="idl-float" interface>float</h4>

The {{float}} type is a floating point numeric
type that corresponds to the set of finite single-precision 32 bit
IEEE 754 floating point numbers. [[!IEEE-754]]

{{float}} constant values in IDL are
represented with <emu-t class="regex"><a href="#prod-decimal">decimal</a></emu-t>
tokens.

The [=type name=] of the
{{float}} type is "<code>Float</code>".

<p class="advisement">
    Unless there are specific reasons to use a 32 bit floating point type,
    specifications should use
    {{double}} rather than {{float}},
    since the set of values that a {{double}} can
    represent more closely matches an ECMAScript Number.
</p>


<h4 oldids="dom-unrestrictedfloat" id="idl-unrestricted-float" interface>unrestricted float</h4>

The {{unrestricted float}} type is a floating point numeric
type that corresponds to the set of all possible single-precision 32 bit
IEEE 754 floating point numbers, finite, non-finite, and special "not a number" values (NaNs). [[!IEEE-754]]

{{unrestricted float}} constant values in IDL are
represented with <emu-t class="regex"><a href="#prod-decimal">decimal</a></emu-t>
tokens.

The [=type name=] of the
{{unrestricted float}} type is "<code>UnrestrictedFloat</code>".


<h4 oldids="dom-double" id="idl-double" interface>double</h4>

The {{double}} type is a floating point numeric
type that corresponds to the set of finite double-precision 64 bit
IEEE 754 floating point numbers. [[!IEEE-754]]

{{double}} constant values in IDL are
represented with <emu-t class="regex"><a href="#prod-decimal">decimal</a></emu-t>
tokens.

The [=type name=] of the
{{double}} type is "<code>Double</code>".


<h4 oldids="dom-unrestricteddouble" id="idl-unrestricted-double" interface>unrestricted double</h4>

The {{unrestricted double}} type is a floating point numeric
type that corresponds to the set of all possible double-precision 64 bit
IEEE 754 floating point numbers, finite, non-finite, and special "not a number" values (NaNs). [[!IEEE-754]]

{{unrestricted double}} constant values in IDL are
represented with <emu-t class="regex"><a href="#prod-decimal">decimal</a></emu-t>
tokens.

The [=type name=] of the
{{unrestricted double}} type is "<code>UnrestrictedDouble</code>".


<h4 oldids="dom-DOMString" id="idl-DOMString" interface>DOMString</h4>

The {{DOMString}} type corresponds to
the set of all possible sequences of [=code units=].
Such sequences are commonly interpreted as UTF-16 encoded strings [[!RFC2781]]
although this is not required.
While {{DOMString}} is defined to be
an OMG IDL boxed [=sequence type|sequence=]&lt;{{unsigned short}}&gt; valuetype
in [[DOM-LEVEL-3-CORE/core#ID-C74D1578|DOM Level 3 Core §The DOMString Type]],
this document defines {{DOMString}} to be an intrinsic type
so as to avoid special casing that sequence type
in various situations where a string is required.

Note: Note also that <emu-val>null</emu-val>
is not a value of type {{DOMString}}.
To allow <emu-val>null</emu-val>, a
[=nullable type|nullable=] {{DOMString}},
written as <code>DOMString?</code> in IDL, needs to be used.

Nothing in this specification requires a {{DOMString}}
value to be a valid UTF-16 string.  For example, a {{DOMString}}
value might include unmatched surrogate pair characters.  However, authors
of specifications using Web IDL might want to obtain a sequence of
[=Unicode scalar values=] given a particular sequence of
[=code units=].

<div algorithm>

    The following algorithm defines a way to
    <dfn id="dfn-obtain-unicode" export lt="obtain Unicode|convert to a sequence of Unicode scalar values">convert a DOMString to a sequence of Unicode scalar values</dfn>:

    1.  Let |S| be the {{DOMString}} value.
    1.  Let |n| be the length of |S|.
    1.  Initialize |i| to 0.
    1.  Initialize |U| to be an empty sequence of Unicode characters.
    1.  While |i| &lt; |n|:
        1.  Let |c| be the [=code unit=] in |S| at index |i|.
        1.  Depending on the value of |c|:
            <dl class="switch">
                 :  |c| &lt; 0xD800 or |c| &gt; 0xDFFF
                 :: Append to |U| the Unicode character with code point |c|.
                 :  0xDC00 ≤ |c| ≤ 0xDFFF
                 :: Append to |U| a <span class="char">U+FFFD REPLACEMENT CHARACTER</span>.
                 :  0xD800 ≤ |c| ≤ 0xDBFF
                 :: <ol class="only">
                        1.  If |i| = |n|−1, then append to |U| a <span class="char">U+FFFD REPLACEMENT CHARACTER</span>.
                        1.  Otherwise, |i| &lt; |n|−1:
                            1.  Let |d| be the code unit in |S| at index
                                |i|+1.
                            1.  If 0xDC00 ≤ |d| ≤ 0xDFFF, then:
                                1.  Let |a| be |c| &amp; 0x3FF.
                                1.  Let |b| be |d| &amp; 0x3FF.
                                1.  Append to |U| the Unicode character with
                                    code point 2<sup>16</sup>+2<sup>10</sup>|a|+|b|.
                                1.  Set |i| to |i|+1.
                            1.  Otherwise, |d| &lt; 0xDC00 or |d| &gt; 0xDFFF.
                                Append to |U| a <span class="char">U+FFFD REPLACEMENT CHARACTER</span>.
                    </ol>
            </dl>
        1.  Set |i| to |i|+1.
    1.  Return |U|.
</div>

There is no way to represent a constant {{DOMString}}
value in IDL, although {{DOMString}} [=dictionary member=] [=dictionary member/default values=]
and [=optional argument|operation optional argument=] [=optional argument/default values=]
can be set to [=value of string literal tokens|the value=] of a
<emu-t class="regex"><a href="#prod-string">string</a></emu-t> literal.

The [=type name=] of the
{{DOMString}} type is "<code>String</code>".


<h4 oldids="dom-ByteString" id="idl-ByteString" interface>ByteString</h4>

The {{ByteString}} type
corresponds to the set of all possible sequences of bytes.
Such sequences might be interpreted as UTF-8 encoded strings [[!RFC3629]]
or strings in some other 8-bit-per-code-unit encoding, although this is not required.

There is no way to represent a constant {{ByteString}}
value in IDL, although {{ByteString}} [=dictionary member=] [=dictionary member/default values=]
and [=optional argument|operation optional argument=] [=optional argument/default values=]
can be set to [=value of string literal tokens|the value=] of a
<emu-t class="regex"><a href="#prod-string">string</a></emu-t> literal.

The [=type name=] of the
{{ByteString}} type is "<code>ByteString</code>".

<p class="advisement">
    Specifications should only use
    {{ByteString}} for interfacing with protocols
    that use bytes and strings interchangeably, such as HTTP.  In general,
    strings should be represented with
    {{DOMString}} values, even if it is expected
    that values of the string will always be in ASCII or some
    8 bit character encoding. [=sequence types|Sequences=] or
    [=frozen array type|frozen arrays=] with {{octet}} or {{byte}}
    elements, {{Uint8Array}}, or {{Int8Array}} should be used for holding
    8 bit data rather than {{ByteString}}.
</p>


<h4 oldids="dom-USVString" id="idl-USVString" interface>USVString</h4>

The {{USVString}} type
corresponds to the set of all possible sequences of
[=Unicode scalar values=],
which are all of the Unicode code points apart from the
surrogate code points.

There is no way to represent a constant {{USVString}}
value in IDL, although {{USVString}} [=dictionary member=] [=dictionary member/default values=]
and [=optional argument|operation optional argument=] [=optional argument/default values=]
can be set to [=value of string literal tokens|the value=] of a
<emu-t class="regex"><a href="#prod-string">string</a></emu-t> literal.

The [=type name=] of the
{{USVString}} type is "<code>USVString</code>".

<p class="advisement">
    Specifications should only use
    {{USVString}} for APIs that perform
    text processing and need a string of Unicode
    scalar values to operate on.  Most APIs that use strings
    should instead be using {{DOMString}},
    which does not make any interpretations of the [=code units=]
    in the string.  When in doubt, use {{DOMString}}.
</p>


<h4 oldids="dom-object" id="idl-object" interface>object</h4>

The {{object}} type corresponds to the set of
all possible non-null object references.

There is no way to represent a constant {{object}}
value in IDL.

To denote a type that includes all possible object references plus the
<emu-val>null</emu-val> value, use the [=nullable type=]
<code class="idl">object?</code>.

The [=type name=] of the
{{object}} type is "<code>Object</code>".

<h4 id="idl-symbol" interface>symbol</h4>

The {{symbol}} type corresponds to the set of all possible symbol values. Symbol values are opaque,
non-{{object}} values which nevertheless have identity (i.e., are only equal to themselves).

There is no way to represent a constant {{symbol}} value in IDL.

The [=type name=] of the {{symbol}} type is "<code>Symbol</code>".


<h4 id="idl-interface" dfn>Interface types</h4>

An [=identifier=] that
identifies an [=interface=] is used to refer to
a type that corresponds to the set of all possible non-null references to objects that
implement that interface.

An IDL value of the interface type is represented just
by an object reference.

There is no way to represent a constant object reference value for
a particular interface type in IDL.

To denote a type that includes all possible references to objects implementing
the given interface plus the <emu-val>null</emu-val> value,
use a [=nullable type=].

The [=type name=] of an interface type
is the [=identifier=] of the interface.


<h4 id="idl-callback-interface" dfn>Callback interface types</h4>

An [=identifier=] that identifies a [=callback interface=] is used to refer to a type that
corresponds to the set of all possible non-null references to objects.

An IDL value of the interface type is represented by a tuple of an object reference and a
<dfn id="dfn-callback-context" export>callback context</dfn>.
The [=callback context=] is a language binding specific value, and is used to store information
about the execution context at the time the language binding specific object reference is
converted to an IDL value.

Note: For ECMAScript objects, the [=callback context=] is used to hold a reference to the
[=incumbent settings object=] at the time the Object value is converted to an IDL callback
interface type value. See [[#es-callback-interface]].

There is no way to represent a constant object reference value for a particular
[=callback interface type=] in IDL.

To denote a type that includes all possible references to objects plus the <emu-val>null</emu-val>
value, use a [=nullable type=].

The [=type name=] of a [=callback interface type=] is the [=identifier=] of the
[=callback interface=].


<h4 id="idl-dictionary" dfn>Dictionary types</h4>

An [=identifier=] that
identifies a [=dictionary=] is used to refer to
a type that corresponds to the set of all dictionaries that adhere to
the dictionary definition.

The literal syntax for [=ordered maps=] may also be used to represent dictionaries, when it is
implicitly understood from context that the map is being treated as an instance of a specific
dictionary type. However, there is no way to represent a constant dictionary value inside IDL
fragments.

The [=type name=] of a dictionary type
is the [=identifier=] of the dictionary.


<h4 id="idl-enumeration" dfn export>Enumeration types</h4>

An [=identifier=] that
identifies an [=enumeration=] is used to
refer to a type whose values are the set of strings (sequences of
[=code units=], as with
{{DOMString}}) that are the
[=enumeration values|enumeration’s values=].

Like {{DOMString}}, there is no way to represent a constant [=enumeration=]
value in IDL, although enumeration-typed [=dictionary member=] [=dictionary member/default values=]
and [=optional argument|operation optional argument=] [=optional argument/default values=]
can be set to [=value of string literal tokens|the value=] of a
<emu-t class="regex"><a href="#prod-string">string</a></emu-t> literal.

The [=type name=] of an enumeration type
is the [=identifier=] of the enumeration.


<h4 id="idl-callback-function" dfn>Callback function types</h4>

An [=identifier=] that identifies
a [=callback function=] is used to refer to
a type whose values are references to objects that are functions with the given signature.

An IDL value of the callback function type is represented by a tuple of an object
reference and a [=callback context=].

Note: As with [=callback interface types=], the [=callback context=] is used to hold a
reference to the [=incumbent settings object=] at
the time an ECMAScript Object value is converted to an IDL
callback function type value.  See [[#es-callback-function]].

There is no way to represent a constant [=callback function=]
value in IDL.

The [=type name=] of a callback function type
is the [=identifier=] of the callback function.


<h4 id="idl-nullable-type">Nullable types — |T|?</h4>

A <dfn id="dfn-nullable-type" export>nullable type</dfn> is an IDL type constructed
from an existing type (called the <dfn id="dfn-inner-type" export for="nullable types">inner type</dfn>),
which just allows the additional value <emu-val>null</emu-val>
to be a member of its set of values.  [=Nullable types=]
are represented in IDL by placing a <span class="char">U+003F QUESTION MARK ("?")</span>
character after an existing type.
The [=nullable types/inner type=] must not be:

*   {{any}},
*   a [=Promise type=],
*   another nullable type, or
*   a [=union type=] that itself [=includes a nullable type=]
    or has a dictionary type as one of its [=flattened member types=].

Note: Although dictionary types can in general be nullable,
they cannot when used as the type of an operation argument or a dictionary member.

Nullable type constant values in IDL are represented in the same way that
constant values of their [=nullable types/inner type=]
would be represented, or with the <emu-t>null</emu-t> token.

The [=type name=] of a nullable type
is the concatenation of the type name of the [=nullable types/inner type=] |T| and
the string "<code>OrNull</code>".

<div class="example">

    For example, a type that allows the values <emu-val>true</emu-val>,
    <emu-val>false</emu-val> and <emu-val>null</emu-val>
    is written as <code class="idl">boolean?</code>:

    <pre highlight="webidl">
        [Exposed=Window]
        interface NetworkFetcher {
          void get(optional boolean? areWeThereYet = false);
        };
    </pre>

    The following [=interface=] has two
    [=attributes=]: one whose value can
    be a {{DOMString}} or the <emu-val>null</emu-val>
    value, and another whose value can be a reference to a <code class="idl">Node</code>
    object or the <emu-val>null</emu-val> value:

    <pre highlight="webidl">
        [Exposed=Window]
        interface Node {
          readonly attribute DOMString? namespaceURI;
          readonly attribute Node? parentNode;
          // ...
        };
    </pre>
</div>


<h4 oldids="dom-sequence" id="idl-sequence" lt="sequence" dfn export>Sequence types — sequence&lt;|T|&gt;</h4>

The <dfn lt="sequence type" export>sequence&lt;|T|&gt;</dfn>
type is a parameterized type whose values are (possibly zero-length) [=lists=] of
values of type |T|.

Sequences are always passed by value.  In
language bindings where a sequence is represented by an object of
some kind, passing a sequence to a [=platform object=]
will not result in a reference to the sequence being kept by that object.
Similarly, any sequence returned from a platform object
will be a copy and modifications made to it will not be visible to the platform object.

The literal syntax for [=lists=] may also be used to represent sequences, when it is implicitly
understood from context that the list is being treated as a sequences. However, there is no way to
represent a constant sequence value inside IDL fragments.

Sequences must not be used as the
type of an [=attribute=] or
[=constant=].

Note: This restriction exists so that it is clear to specification writers
and API users that [=sequence types|sequences=]
are copied rather than having references
to them passed around.  Instead of a writable [=attribute=] of a sequence
type, it is suggested that a pair of [=operations=] to get and set the
sequence is used.

The [=type name=] of a sequence type
is the concatenation of the type name for |T| and
the string "<code>Sequence</code>".

Any [=list=] can be implicitly treated as a <code>sequence&lt;|T|&gt;</code>, as long as it contains
only [=list/items=] that are of type |T|.


<h4 id="idl-record" lt="record" dfn export>Record types — record&lt;|K|, |V|&gt;</h4>

A <dfn export>record type</dfn> is a parameterized type whose values are [=ordered maps=] with
[=map/keys=] that are instances of |K| and [=map/values=] that are instances of |V|. |K| must be one
of {{DOMString}}, {{USVString}}, or {{ByteString}}.

The literal syntax for [=ordered maps=] may also be used to represent records, when it is implicitly
understood from context that the map is being treated as a record. However, there is no way to
represent a constant record value inside IDL fragments.

Records are always passed by value. In language bindings where a record
is represented by an object of some kind, passing a record
to a [=platform object=] will not result in a reference to the record
being kept by that object. Similarly, any record returned from a
platform object will be a copy and modifications made to it will not be visible
to the platform object.

Records must not be used as the type of an [=attribute=] or
[=constant=].

The [=type name=] of a record type is the concatenation of the type
name for |K|, the type name for |V| and the string "<code>Record</code>".

Any [=ordered map=] can be implicitly treated as a <code>record&lt;|K|, |V|&gt;</code>, as long as
it contains only [=map/entries=] whose [=map/keys=] are all of of type |K| and whose [=map/values=]
are all of type |V|.


<h4 oldids="dom-promise" id="idl-promise" interface lt="Promise|Promise&lt;T&gt;">Promise types — Promise&lt;|T|&gt;</h4>

A <dfn id="dfn-promise-type" export>promise type</dfn> is a parameterized type
whose values are references to objects that “is used as a place holder
for the eventual results of a deferred (and possibly asynchronous) computation
result of an asynchronous operation”.
See <a href="https://tc39.github.io/ecma262/#sec-promise-objects">section 25.4</a>
of the ECMAScript specification for details on the semantics of promise objects.

Promise types are non-nullable, but |T| may be nullable.

There is no way to represent a promise value in IDL.

The [=type name=] of a promise type
is the concatenation of the type name for |T| and
the string "<code>Promise</code>".


<h4 id="idl-union">Union types</h4>

A <dfn id="dfn-union-type" export>union type</dfn> is a type whose set of values
is the union of those in two or more other types.  Union types (matching
<emu-nt><a href="#prod-UnionType">UnionType</a></emu-nt>)
are written as a series of types separated by the <emu-t>or</emu-t> keyword
with a set of surrounding parentheses.
The types which comprise the union type are known as the
union’s <dfn id="dfn-union-member-type" for="union" export>member types</dfn>.

<div class="note">

    For example, you might write <code>(Node or DOMString)</code>
    or <code>(double or sequence&lt;double&gt;)</code>.  When applying a
    <emu-t>?</emu-t> suffix to a
    [=union type=]
    as a whole, it is placed after the closing parenthesis,
    as in <code>(Node or DOMString)?</code>.

    Note that the [=member types=]
    of a union type do not descend into nested union types.  So for
    <code>(double or (sequence&lt;long&gt; or Event) or (Node or DOMString)?)</code> the member types
    are <code>double</code>, <code>(sequence&lt;long&gt; or Event)</code> and
    <code>(Node or DOMString)?</code>.

</div>

Like the {{any}} type, values of
union types have a [=specific type=],
which is the particular [=member type=]
that matches the value.

<div algorithm>

    The <dfn id="dfn-flattened-union-member-types" for="union" export>flattened member types</dfn>
    of a [=union type=], possibly [=annotated type|annotated=], is a set of types determined as
    follows:

    1.  Let |T| be the [=union type=].
    1.  Initialize |S| to ∅.
    1.  For each [=member type=] |U| of |T|:
        1.  If |U| is an [=annotated type=], then
            set |U| to be the [=annotated types/inner type=] of |U|.
        1.  If |U| is a [=nullable type=], then
            set |U| to be the [=nullable types/inner type=] of |U|.
        1.  If |U| is a [=union type=], then
            add to |S| the [=flattened member types=]
            of |U|.
        1.  Otherwise, |U| is not a [=union type=].
            Add |U| to |S|.
    1.  Return |S|.
</div>


Note: For example, the [=flattened member types=]
of the [=union type=]
<code>(Node or (sequence&lt;long&gt; or Event) or (XMLHttpRequest or DOMString)? or sequence&lt;(sequence&lt;double&gt; or NodeList)&gt;)</code>
are the six types <code>Node</code>, <code>sequence&lt;long&gt;</code>, <code>Event</code>,
<code>XMLHttpRequest</code>, <code>DOMString</code> and
<code>sequence&lt;(sequence&lt;double&gt; or NodeList)&gt;</code>.

<div algorithm>

    The <dfn id="dfn-number-of-nullable-member-types" export>number of nullable member types</dfn>
    of a [=union type=] is an integer
    determined as follows:

    1.  Let |T| be the [=union type=].
    1.  Initialize |n| to 0.
    1.  For each [=member type=] |U| of |T|:
        1.  If |U| is a [=nullable type=], then:
            1.  Set |n| to |n| + 1.
            1.  Set |U| to be the [=nullable types/inner type=] of |U|.
        1.  If |U| is a [=union type=], then:
            1.  Let |m| be the [=number of nullable member types=] of |U|.
            1.  Set |n| to |n| + |m|.
    1.  Return |n|.
</div>

The {{any}} type must not
be used as a [=member types|union member type=].

The [=number of nullable member types=]
of a [=union type=] must
be 0 or 1, and if it is 1 then the union type must also not have
a [=dictionary type=] in its [=flattened member types=].

A type <dfn id="dfn-includes-a-nullable-type" export>includes a nullable type</dfn> if:

*   the type is a [=nullable type=], or
*   the type is an [=annotated type=] and its [=annotated types/inner type=] is a nullable type, or
*   the type is a [=union type=] and its
    [=number of nullable member types=] is 1.

Each pair of [=flattened member types=]
in a [=union type=], <var ignore>T</var> and <var ignore>U</var>,
must be [=distinguishable=].

[=Union type=] constant values
in IDL are represented in the same way that constant values of their
[=member types=] would be
represented.

The [=type name=] of a union
type is formed by taking the type names of each member type, in order,
and joining them with the string "<code>Or</code>".

<div data-fill-with="grammar-UnionType"></div>

<div data-fill-with="grammar-UnionMemberType"></div>

<div data-fill-with="grammar-UnionMemberTypes"></div>

<div data-fill-with="grammar-DistinguishableType"></div>


<h4 id="idl-annotated-types">Annotated types</h4>

Additional types can be created from existing ones by specifying certain [=extended attributes=] on
the existing types. Such types are called <dfn export>annotated types</dfn>, and the types they
annotate are called <dfn export for="annotated types" lt="inner type">inner types</dfn>.

<div class="example">
    <code>[Clamp] long</code> defines a new [=annotated type=], whose behavior is based on that of
    the [=annotated types/inner type=] {{long}}, but modified as specified by the [{{Clamp}}]
    extended attribute.
</div>

The following extended attributes are <dfn for="extended attributes">applicable to types</dfn>:
[{{AllowShared}}],
[{{Clamp}}],
[{{EnforceRange}}], and
[{{TreatNullAs}}].

<div algorithm>
    The <dfn for="IDL type" lt="extended attribute associated with|extended attributes associated with">extended attributes associated with</dfn>
    an IDL type |type| are determined as follows:

    1.  Let |extended attributes| be a new empty [=ordered set|set=].
    1.  If |type| appears as part of a
        <emu-nt><a href="#prod-TypeWithExtendedAttributes">TypeWithExtendedAttributes</a></emu-nt>
        production, [=set/append=] each of the [=extended attributes=] present in the production's
        <emu-nt><a href="#prod-ExtendedAttributeList">ExtendedAttributeList</a></emu-nt> to
        |extended attributes|.

        <div class="example">
            <pre class="idl">
                [Exposed=Window]
                interface I {
                    attribute [XAttr] long attrib;
                    void f1(sequence<[XAttr] long> arg);
                    void f2(optional [XAttr] long arg);

                    maplike&lt;[XAttr2] DOMString, [XAttr3] long>;
                };

                dictionary D {
                    required [XAttr] long member;
                };
            </pre>
        </div>
    1.  If |type| is a [=member type=] of a [=union type=] |U|, [=set/append=] each of the
        [=extended attributes associated with=] |U| to |extended attributes|.

        <div class="example">
            <pre class="idl">
                [Exposed=Window]
                interface I {
                    attribute [XAttr] (long or Node) attrib;
                };
            </pre>
        </div>
    1.  If |type| appears as part of a <emu-nt><a href="#prod-Type">Type</a></emu-nt> production
        directly within an <emu-nt><a href="#prod-Argument">Argument</a></emu-nt> production,
        [=set/append=] to |extended attributes| all of the [=extended attributes=] present in the
        production's
        <emu-nt><a href="#prod-ExtendedAttributeList">ExtendedAttributeList</a></emu-nt> that are
        [=applicable to types=].

        <div class="example">
            <pre class="idl">
                [Exposed=Window]
                interface I {
                    void f([XAttr] long attrib);
                };
            </pre>

            Note that this is an example of this step only if [<code>XAttr</code>] is
            [=applicable to types=]; otherwise [<code>XAttr</code>] applies to the argument, and not
            the argument's type.
        </div>
    1.  If |type| appears as part of a <emu-nt><a href="#prod-Type">Type</a></emu-nt> production
        directly within an <emu-nt><a href="#prod-DictionaryMember">DictionaryMember</a></emu-nt>
        production, [=set/append=] to |extended attributes| all of the [=extended attributes=]
        present in the production's
        <emu-nt><a href="#prod-ExtendedAttributeList">ExtendedAttributeList</a></emu-nt> that are
        [=applicable to types=].

        <div class="example">
            <pre class="idl">
                dictionary D {
                    [XAttr] long member;
                };
            </pre>

            Note that this is an example of this step only if [<code>XAttr</code>] is
            [=applicable to types=]; otherwise [<code>XAttr</code>] applies to the dictionary
            member, and not the member's type.
        </div>
    1.  If |type| is a [=typedef=], [=set/append=] the [=extended attributes associated with=] the
        [=type being given a new name=] to |extended attributes|.

        <div class="example">
            <pre class="idl">
                typedef [XAttr] long xlong;
            </pre>
        </div>
    1. Return |extended attributes|.
</div>

For any type, the [=extended attributes associated with=] it must only contain
[=extended attributes=] that are [=applicable to types=].

The [=type name=] of a type associated with [=extended attributes=] is the concatenation of the
type name of the original type with the set of strings corresponding to the [=identifiers=] of each
[=extended attribute associated with=] the type, sorted in lexicographic order.

<div class="example">
    The [=type name=] for a type of the form <code>[B, A] long?</code> is "LongOrNullAB".
</div>

<h4 id="idl-buffer-source-types">Buffer source types</h4>

There are a number of types that correspond to sets of all possible non-null
references to objects that represent a buffer of data or a view on to a buffer of
data.  The table below lists these types and the kind of buffer or view they represent.

<table class="vert data">
    <tr><th>Type</th><th>Kind of buffer</th></tr>
    <tr><td><dfn id="idl-ArrayBuffer" interface>ArrayBuffer</dfn></td><td>An object that holds a pointer (which may be null) to a buffer of a fixed number of bytes</td></tr>
    <tr><td><dfn id="idl-DataView" interface>DataView</dfn></td><td>A view on to an {{ArrayBuffer}} that allows typed access to integers and floating point values stored at arbitrary offsets into the buffer</td></tr>
        <tr><td>
            <dfn id="idl-Int8Array" interface>Int8Array</dfn>,<br/>
            <dfn id="idl-Int16Array" interface>Int16Array</dfn>,<br/>
        <dfn id="idl-Int32Array" interface>Int32Array</dfn></td>
    <td>A view on to an {{ArrayBuffer}} that exposes it as an array of two’s complement signed integers of the given size in bits</td></tr>
        <tr><td>
            <dfn id="idl-Uint8Array" interface>Uint8Array</dfn>,<br/>
            <dfn id="idl-Uint16Array" interface>Uint16Array</dfn>,<br/>
        <dfn id="idl-Uint32Array" interface>Uint32Array</dfn></td>
    <td>A view on to an {{ArrayBuffer}} that exposes it as an array of unsigned integers of the given size in bits</td></tr>
        <tr><td><dfn id="idl-Uint8ClampedArray" interface>Uint8ClampedArray</dfn></td>
    <td>A view on to an {{ArrayBuffer}} that exposes it as an array of unsigned 8 bit integers with clamped conversions</td></tr>
        <tr><td>
            <dfn id="idl-Float32Array" interface>Float32Array</dfn>,<br/>
        <dfn id="idl-Float64Array" interface>Float64Array</dfn></td>
    <td>A view on to an {{ArrayBuffer}} that exposes it as an array of IEEE 754 floating point numbers of the given size in bits</td></tr>
</table>

Note: These types all correspond to classes defined in ECMAScript.

There is no way to represent a constant value of any of these types in IDL.

The [=type name=] of all
of these types is the name of the type itself.

At the specification prose level, IDL [=buffer source types=]
are simply references to objects.  To inspect or manipulate the bytes inside the buffer,
specification prose must first either
<dfn id="dfn-get-buffer-source-reference" export lt="get a reference to the buffer source">get a reference to the bytes held by the buffer source</dfn>
or <dfn id="dfn-get-buffer-source-copy" export lt="get a copy of the buffer source">get a copy of the bytes held by the buffer source</dfn>.
With a reference to the buffer source’s bytes, specification prose can get or set individual
byte values using that reference.

<div class="advisement">

    Extreme care must be taken when writing specification text that gets a reference
    to the bytes held by a buffer source, as the underlying data can easily be changed
    by the script author or other APIs at unpredictable times.  If you are using a buffer source type
    as an operation argument to obtain a chunk of binary data that will not be modified,
    it is strongly recommended to get a copy of the buffer source’s bytes at the beginning
    of the prose defining the operation.

    Requiring prose to explicitly get a reference to or copy of the bytes is intended to
    help specification reviewers look for problematic uses of these buffer source types.

</div>

<div class="note">

    When designing APIs that take a buffer, it is recommended to use the
    {{BufferSource}} typedef rather than {{ArrayBuffer}}
    or any of the view types.

    When designing APIs that create and return a buffer, it is recommended
    to use the {{ArrayBuffer}} type rather than
    {{Uint8Array}}.

</div>

Attempting to [=get a reference to the buffer source|get a reference to=] or
[=get a copy of the buffer source|get a copy of the bytes held by a buffer source=]
when the {{ArrayBuffer}} has been [=ArrayBuffer/detached=]
will fail in a language binding-specific manner.

Note: See [[#es-buffer-source-types]] below for
how interacting with buffer source types works in the ECMAScript language binding.

<p class="issue">
    We should include an example of specification text that uses these types and terms.
</p>

<pre class="grammar" id="prod-BufferRelatedType">
    BufferRelatedType :
        "ArrayBuffer"
        "DataView"
        "Int8Array"
        "Int16Array"
        "Int32Array"
        "Uint8Array"
        "Uint16Array"
        "Uint32Array"
        "Uint8ClampedArray"
        "Float32Array"
        "Float64Array"
</pre>


<h4 oldids="dom-FrozenArray" id="idl-frozen-array" interface lt="FrozenArray|FrozenArray&lt;T&gt;">Frozen array types — FrozenArray&lt;|T|&gt;</h4>

A <dfn id="dfn-frozen-array-type" export>frozen array type</dfn> is a parameterized
type whose values are references to objects that hold a fixed length array
of unmodifiable values.  The values in the array are of type |T|.

Since <a interface lt="FrozenArray">FrozenArray&lt;|T|&gt;</a> values
are references, they are unlike [=sequence types=],
which are lists of values that are passed by value.

There is no way to represent a constant frozen array value in IDL.

The [=type name=] of a frozen array
type is the concatenation of the type name for |T| and the string
"<code>Array</code>".


<h3 id="idl-extended-attributes">Extended attributes</h3>

An <dfn id="dfn-extended-attribute" export>extended attribute</dfn> is an annotation
that can appear on
[=definitions=],
types as [=annotated types=],
[=interface members=],
[=interface mixin members=],
[=callback interface members=],
[=namespace members=],
[=dictionary members=],
and [=operation=] arguments, and
is used to control how language bindings will handle those constructs.
Extended attributes are specified with an
<emu-nt><a href="#prod-ExtendedAttributeList">ExtendedAttributeList</a></emu-nt>,
which is a square bracket enclosed, comma separated list of
<emu-nt><a href="#prod-ExtendedAttribute">ExtendedAttribute</a></emu-nt>s.

The <emu-nt><a href="#prod-ExtendedAttribute">ExtendedAttribute</a></emu-nt>
grammar symbol matches nearly any sequence of tokens, however the
[=extended attributes=]
defined in this document only accept a more restricted syntax.
Any extended attribute encountered in an
[=IDL fragment=] is
matched against the following five grammar symbols to determine
which form (or forms) it is in:

<table class="vert data">
    <tr>
        <th>Grammar symbol</th>
        <th>Form</th>
        <th>Example</th>
    </tr>
    <tr>
        <td>
            <emu-nt><a href="#prod-ExtendedAttributeNoArgs">ExtendedAttributeNoArgs</a></emu-nt>
        </td>
        <td>
            <dfn id="dfn-xattr-no-arguments" for="extended attribute" export>takes no arguments</dfn>
        </td>
        <td>
            <code>[Replaceable]</code>
        </td>
    </tr>
    <tr>
        <td>
            <emu-nt><a href="#prod-ExtendedAttributeArgList">ExtendedAttributeArgList</a></emu-nt>
        </td>
        <td>
            <dfn id="dfn-xattr-argument-list" for="extended attribute" export>takes an argument list</dfn>
        </td>
        <td>
            Not currently used; previously used by <code>[Constructor(double x, double y)]</code>
        </td>
    </tr>
    <tr>
        <td>
            <emu-nt><a href="#prod-ExtendedAttributeNamedArgList">ExtendedAttributeNamedArgList</a></emu-nt>
        </td>
        <td>
            <dfn id="dfn-xattr-named-argument-list" for="extended attribute" export>takes a named argument list</dfn>
        </td>
        <td>
            <code>[NamedConstructor=Image(DOMString src)]</code>
        </td>
    </tr>
    <tr>
        <td>
            <emu-nt><a href="#prod-ExtendedAttributeIdent">ExtendedAttributeIdent</a></emu-nt>
        </td>
        <td>
            <dfn id="dfn-xattr-identifier" for="extended attribute" export>takes an identifier</dfn>
        </td>
        <td>
            <code>[PutForwards=name]</code>
        </td>
    </tr>
    <tr>
        <td>
            <emu-nt><a href="#prod-ExtendedAttributeIdentList">ExtendedAttributeIdentList</a></emu-nt>
        </td>
        <td>
            <dfn id="dfn-xattr-identifier-list" for="extended attribute" export>takes an identifier list</dfn>
        </td>
        <td>
            <code>[Exposed=(Window,Worker)]</code>
        </td>
    </tr>

</table>

This specification defines a number of extended attributes that
are applicable to the ECMAScript language binding, which are described in
[[#es-extended-attributes]].
Each extended attribute definition will state which of the above
five forms are allowed.

<pre class="grammar" id="prod-ExtendedAttributeList">
    ExtendedAttributeList :
        "[" ExtendedAttribute ExtendedAttributes "]"
        ε
</pre>

<pre class="grammar" id="prod-ExtendedAttributes">
    ExtendedAttributes :
        "," ExtendedAttribute ExtendedAttributes
        ε
</pre>

<pre class="grammar" id="prod-ExtendedAttribute">
    ExtendedAttribute :
        "(" ExtendedAttributeInner ")" ExtendedAttributeRest
        "[" ExtendedAttributeInner "]" ExtendedAttributeRest
        "{" ExtendedAttributeInner "}" ExtendedAttributeRest
        Other ExtendedAttributeRest
</pre>

<pre class="grammar" id="prod-ExtendedAttributeRest">
    ExtendedAttributeRest :
        ExtendedAttribute
        ε
</pre>

<pre class="grammar" id="prod-ExtendedAttributeInner">
    ExtendedAttributeInner :
        "(" ExtendedAttributeInner ")" ExtendedAttributeInner
        "[" ExtendedAttributeInner "]" ExtendedAttributeInner
        "{" ExtendedAttributeInner "}" ExtendedAttributeInner
        OtherOrComma ExtendedAttributeInner
        ε
</pre>

<pre class="grammar" id="prod-Other">
    Other :
        integer
        decimal
        identifier
        string
        other
        "-"
        "-Infinity"
        "."
        "..."
        ":"
        ";"
        "&lt;"
        "="
        "&gt;"
        "?"
        "ByteString"
        "DOMString"
        "FrozenArray"
        "Infinity"
        "NaN"
        "Promise"
        "USVString"
        "any"
        "boolean"
        "byte"
        "double"
        "false"
        "float"
        "long"
        "null"
        "object"
        "octet"
        "or"
        "optional"
        "record"
        "sequence"
        "short"
        "symbol"
        "true"
        "unsigned"
        "void"
        ArgumentNameKeyword
        BufferRelatedType
</pre>

<pre class="grammar" id="prod-OtherOrComma">
    OtherOrComma :
        Other
        ","
</pre>

<pre class="grammar" id="prod-IdentifierList">
    IdentifierList :
        identifier Identifiers
</pre>

<pre class="grammar" id="prod-Identifiers">
    Identifiers :
        "," identifier Identifiers
        ε
</pre>

<pre class="grammar" id="prod-ExtendedAttributeNoArgs">
    ExtendedAttributeNoArgs :
        identifier
</pre>

<pre class="grammar" id="prod-ExtendedAttributeArgList">
    ExtendedAttributeArgList :
        identifier "(" ArgumentList ")"
</pre>

<pre class="grammar" id="prod-ExtendedAttributeIdent">
    ExtendedAttributeIdent :
        identifier "=" identifier
</pre>

<pre class="grammar" id="prod-ExtendedAttributeIdentList">
    ExtendedAttributeIdentList :
        identifier "=" "(" IdentifierList ")"
</pre>

<pre class="grammar" id="prod-ExtendedAttributeNamedArgList">
    ExtendedAttributeNamedArgList :
        identifier "=" identifier "(" ArgumentList ")"
</pre>


<h2 id="ecmascript-binding">ECMAScript binding</h2>

This section describes how definitions written with the IDL defined in
[[#idl]] correspond to particular constructs
in ECMAScript, as defined by the <cite>ECMAScript Language Specification</cite>
[[!ECMA-262]].

Unless otherwise specified, objects defined in this section are ordinary objects as described in
[=ECMA-262 Ordinary object internal methods and internal slots=], and if the
object is a [=function object=], [=ECMA-262 Built-in function objects=].

This section may redefine certain internal methods and/or internal slots of objects. Other
specifications may also override the definitions of any internal method and/or internal slots of a
[=platform object=] that is an instance of an [=interface=]. These objects with changed semantics
shall be treated in accordance with the rules for exotic objects.

<p class="advisement">
    As overriding internal ECMAScript object methods is a low level operation and
    can result in objects that behave differently from ordinary objects,
    this facility should not be used unless necessary
    for security or compatibility. <span class="non-normative">This is currently used to define the
    {{HTMLAllCollection}} and {{Location}} interfaces. [[HTML]]</span>
</p>

Unless otherwise specified, exotic objects defined in this section and other specifications have the
same [=ordinary object/internal slots=] as ordinary objects, and all of the internal methods for
which alternative definitions are not given are the same as [=ordinary object/internal
methods|those=] of ordinary objects.

Unless otherwise specified, the \[[Extensible]] internal slot
of objects defined in this section has the value <emu-val>true</emu-val>.

Unless otherwise specified, the \[[Prototype]] internal slot
of objects defined in this section is {{%ObjectPrototype%}}.

Some objects described in this section are defined to have a <dfn id="dfn-class-string" export>class string</dfn>,
which is the string to include in the string returned from Object.prototype.toString.

If an object has a [=class string=] |classString|, then the object must,
at the time it is created, have a property whose name is the {{@@toStringTag}} symbol
with PropertyDescriptor{\[[Writable]]: <emu-val>false</emu-val>,
\[[Enumerable]]: <emu-val>false</emu-val>, \[[Configurable]]: <emu-val>true</emu-val>,
\[[Value]]: |classString|}.

<p id="ecmascript-abstractop">
    Algorithms in this section use the conventions described in [=ECMA-262
    Algorithm conventions=], such as the use of steps and substeps, the use of mathematical
    operations, and so on.  This section may also reference abstract operations
    and notations defined in other parts of ECMA-262.
</p>

When an algorithm says to
<dfn noexport lt="ECMAScript throw" local-lt="throw" for="ECMAScript" id="ecmascript-throw">throw</dfn> a <code>|Something|Error</code>
then this means to construct a new ECMAScript <code>|Something|Error</code> object in
the [=current Realm=] and to throw it, just as the algorithms in ECMA-262 do.

Note that algorithm steps can call in to other algorithms and abstract operations and
not explicitly handle exceptions that are thrown from them.  When an exception
is thrown by an algorithm or abstract operation and it is not explicitly
handled by the caller, then it is taken to end the algorithm and propagate out
to its caller, and so on.

<div class="example">

    <div algorithm="example algorithm">

        Consider the following algorithm:

        1.  Let |x| be the ECMAScript value passed in to this algorithm.
        1.  Let |y| be the result of calling <a abstract-op>ToString</a>(|x|).
        1.  Return |y|.
    </div>

    Since <a abstract-op>ToString</a> can throw an exception (for example if passed the object
    <code>({ toString: function() { throw 1 } })</code>), and the exception is
    not handled in the above algorithm, if one is thrown then it causes this
    algorithm to end and for the exception to propagate out to its caller, if there
    is one.

</div>


<h3 id="es-environment">ECMAScript environment</h3>

In an ECMAScript implementation of a given set of
[=IDL fragments=],
there will exist a number of ECMAScript objects that correspond to
definitions in those [=IDL fragments=].
These objects are termed the <dfn id="dfn-initial-object" export>initial objects</dfn>,
and comprise the following:

*   [=interface objects=]
*   [=legacy callback interface objects=]
*   [=named constructors=]
*   [=interface prototype objects=]
*   [=named properties objects=]
*   [=iterator prototype objects=]
*   [=attribute getters=]
*   [=attribute setters=]
*   <a href="#es-operations">the function objects that correspond to operations</a>
*   <a href="#es-stringifier">the function objects that correspond to stringifiers</a>
*   <a href="#es-iterators">the function objects that correspond to iterators</a>
*   [=map size getters=]

Each [=Realm=]
must have its own unique set of each of
the [=initial objects=], created
before control enters any ECMAScript execution context associated with the
Realm, but after the [=Realm/global object=] for that Realm is created.  The \[[Prototype]]s
of all initial objects in a given [=Realm=] must come from
that same [=Realm=].

<div class="example">

    In an HTML user agent, multiple [=Realms=] can exist when
    multiple frames or windows are created.  Each frame or window will have
    its own set of [=initial objects=],
    which the following HTML document demonstrates:

    <pre highlight="html">
        &lt;!DOCTYPE html&gt;
        &lt;title&gt;Different Realms&lt;/title&gt;
        &lt;iframe id=a&gt;&lt;/iframe&gt;
        &lt;script&gt;
        var iframe = document.getElementById("a");
        var w = iframe.contentWindow;              // The global object in the frame

        Object == w.Object;                        // Evaluates to false, per ECMA-262
        Node == w.Node;                            // Evaluates to false
        iframe instanceof w.Node;                  // Evaluates to false
        iframe instanceof w.Object;                // Evaluates to false
        iframe.appendChild instanceof Function;    // Evaluates to true
        iframe.appendChild instanceof w.Function;  // Evaluates to false
        &lt;/script&gt;
    </pre>
</div>

Note: All [=interfaces=] define which [=Realms=] they are [=exposed=] in.
This allows, for example, [=Realms=] for Web Workers to [=expose=]
different sets of supported interfaces from those exposed in Realms
for Web pages.

Although at the time of this writing the ECMAScript specification does not reflect this,
every ECMAScript object must have an <dfn id="dfn-associated-realm" export>associated [=Realm=]</dfn>. The mechanisms
for associating objects with Realms are, for now, underspecified. However, we note that
in the case of [=platform objects=], the
associated Realm is equal to the object's [=relevant Realm=], and
for non-exotic [=function objects=] (i.e. not [=ECMAScript/callable=] proxies, and not bound functions)
the associated Realm is equal to the value of the [=function object=]'s \[[Realm]] internal
slot.


<h3 id="es-type-mapping">ECMAScript type mapping</h3>

This section describes how types in the IDL map to types in ECMAScript.

Each sub-section below describes how values of a given IDL type are represented
in ECMAScript.  For each IDL type, it is described how ECMAScript values are
<dfn id="dfn-convert-ecmascript-to-idl-value" export lt="converted to an IDL value|converted to IDL values">converted to an IDL value</dfn>
when passed to a [=platform object=] expecting that type, and how IDL values
of that type are <dfn id="dfn-convert-idl-to-ecmascript-value" export lt="converted to an ECMAScript value|converted to ECMAScript values">converted to ECMAScript values</dfn>
when returned from a platform object.

Note that the sub-sections and algorithms below also apply to [=annotated types=] created by applying
extended attributes to the types named in their headers.


<h4 id="es-any">any</h4>

Since the IDL {{any}} type
is the union of all other IDL types, it can correspond to any
ECMAScript value type.

<div id="es-to-any" algorithm="convert an ECMAScript value to any">

    An ECMAScript value |V| is [=converted to an IDL value|converted=]
    to an IDL {{any}} value by running the following algorithm:

    1.  If |V| is <emu-val>undefined</emu-val>, then
        return an {{object}} reference to a special object that represents
        the ECMAScript <emu-val>undefined</emu-val> value.
    1.  If |V| is <emu-val>null</emu-val>, then
        return the <emu-val>null</emu-val> {{object|object?}} reference.
    1.  If <a abstract-op>Type</a>(|V|) is Boolean, then
        return the {{boolean}} value that represents the same truth value.
    1.  If <a abstract-op>Type</a>(|V|) is Number, then
        return the result of <a href="#es-to-unrestricted-double">converting</a> |V|
        to an {{unrestricted double}}.
    1.  If <a abstract-op>Type</a>(|V|) is String, then
        return the result of <a href="#es-DOMString">converting</a> |V|
        to a {{DOMString}}.
    1.  If <a abstract-op>Type</a>(|V|) is Symbol, then
        return the result of <a href="#es-symbol">converting</a> |V|
        to a {{symbol}}.
    1.  If <a abstract-op>Type</a>(|V|) is Object, then
        return an IDL {{object}} value that references |V|.
</div>

<p id="any-to-es">
    An IDL {{any}} value is
    [=converted to an ECMAScript value=]
    as follows.  If the value is an {{object}}
    reference to a special object that represents an ECMAScript <emu-val>undefined</emu-val>
    value, then it is converted to the ECMAScript
    <emu-val>undefined</emu-val> value.  Otherwise,
    the rules for converting the [=specific type=]
    of the IDL {{any}} value
    as described in the remainder of this section are performed.
</p>


<h4 id="es-void">void</h4>

<p id="es-to-void">
    An ECMAScript value |V| is [=converted to an IDL value|converted=] to an IDL {{void}} value by
    returning the unique {{void}} value, ignoring |V|.
</p>

<p id="void-to-es">
    The unique IDL {{void}} value is [=converted to an ECMAScript value|converted=] to the
    ECMAScript <emu-val>undefined</emu-val> value.
</p>


<h4 id="es-boolean">boolean</h4>

<div id="es-to-boolean" algorithm="convert an ECMAScript value to boolean">

    An ECMAScript value |V| is [=converted to an IDL value|converted=]
    to an IDL {{boolean}} value by running the following algorithm:

    1.  Let |x| be the result of computing <a abstract-op>ToBoolean</a>(|V|).
    1.  Return the IDL {{boolean}} value that is the one that
        represents the same truth value as the
        ECMAScript Boolean value |x|.
</div>

<p id="boolean-to-es">
    The IDL {{boolean}} value <code class="idl">true</code>
    is [=converted to an ECMAScript value|converted=] to
    the ECMAScript <emu-val>true</emu-val> value and the IDL {{boolean}}
    value <code class="idl">false</code> is converted to the ECMAScript
    <emu-val>false</emu-val> value.
</p>

<h4 id="es-integer-types">Integer types</h4>

Mathematical operations used in this section,
including those defined in [=ECMA-262 Algorithm conventions=],
are to be understood as computing exact mathematical results
on mathematical real numbers.

In effect, where <var ignore>x</var> is a Number value,
“operating on <var ignore>x</var>” is shorthand for
“operating on the mathematical real number that represents the same numeric value as <var ignore>x</var>”.

<h5 id="es-byte">byte</h5>

<div id="es-to-byte" algorithm="convert an ECMAScript value to byte">

    An ECMAScript value |V| is [=converted to an IDL value|converted=]
    to an IDL {{byte}} value by running the following algorithm:

    1.  Let |x| be [=?=] <a abstract-op>ConvertToInt</a>(|V|, 8, "<code>signed</code>").
    1.  Return the IDL {{byte}} value that represents the same numeric value as |x|.
</div>

<p id="byte-to-es">
    The result of [=converted to an ECMAScript value|converting=]
    an IDL {{byte}} value to an ECMAScript
    value is a Number that represents
    the same numeric value as the IDL {{byte}} value.
    The Number value will be an integer in the range [−128, 127].
</p>


<h5 id="es-octet">octet</h5>

<div id="es-to-octet" algorithm="convert an ECMAScript value to octet">

    An ECMAScript value |V| is [=converted to an IDL value|converted=]
    to an IDL {{octet}} value by running the following algorithm:

    1.  Let |x| be [=?=] <a abstract-op>ConvertToInt</a>(|V|, 8, "<code>unsigned</code>").
    1.  Return the IDL {{octet}} value that represents the same numeric value as |x|.
</div>

<p id="octet-to-es">
    The result of [=converted to an ECMAScript value|converting=]
    an IDL {{octet}} value to an ECMAScript
    value is a Number that represents
    the same numeric value as the IDL
    {{octet}} value.
    The Number value will be an integer in the range [0, 255].
</p>


<h5 id="es-short">short</h5>

<div id="es-to-short" algorithm="convert an ECMAScript value to short">

    An ECMAScript value |V| is [=converted to an IDL value|converted=]
    to an IDL {{short}} value by running the following algorithm:

    1.  Let |x| be [=?=] <a abstract-op>ConvertToInt</a>(|V|, 16, "<code>signed</code>").
    1.  Return the IDL {{short}} value that represents the same numeric value as |x|.

</div>

<p id="short-to-es">
    The result of [=converted to an ECMAScript value|converting=]
    an IDL {{short}} value to an ECMAScript
    value is a Number that represents the
    same numeric value as the IDL
    {{short}} value.
    The Number value will be an integer in the range [−32768, 32767].
</p>


<h5 id="es-unsigned-short">unsigned short</h5>

<div id="es-to-unsigned-short" algorithm="convert an ECMAScript value to unsigned short">

    An ECMAScript value |V| is [=converted to an IDL value|converted=]
    to an IDL {{unsigned short}} value by running the following algorithm:

    1.  Let |x| be [=?=] <a abstract-op>ConvertToInt</a>(|V|, 16, "<code>unsigned</code>").
    1.  Return the IDL {{unsigned short}} value that represents the same numeric value as |x|.
</div>

<p id="unsigned-short-to-es">
    The result of [=converted to an ECMAScript value|converting=]
    an IDL {{unsigned short}} value to an ECMAScript
    value is a Number that
    represents the same numeric value as the IDL
    {{unsigned short}} value.
    The Number value will be an integer in the range [0, 65535].
</p>


<h5 id="es-long">long</h5>

<div id="es-to-long" algorithm="convert an ECMAScript value to long">

    An ECMAScript value |V| is [=converted to an IDL value|converted=]
    to an IDL {{long}} value by running the following algorithm:

    1.  Let |x| be [=?=] <a abstract-op>ConvertToInt</a>(|V|, 32, "<code>signed</code>").
    1.  Return the IDL {{long}} value that represents the same numeric value as |x|.
</div>

<p id="long-to-es">
    The result of [=converted to an ECMAScript value|converting=]
    an IDL {{long}} value to an ECMAScript
    value is a Number that
    represents the same numeric value as the IDL
    {{long}} value.
    The Number value will be an integer in the range [−2147483648, 2147483647].
</p>


<h5 id="es-unsigned-long">unsigned long</h5>

<div id="es-to-unsigned-long" algorithm="convert an ECMAScript value to unsigned long">

    An ECMAScript value |V| is [=converted to an IDL value|converted=]
    to an IDL {{unsigned long}} value  by running the following algorithm:

    1.  Let |x| be [=?=] <a abstract-op>ConvertToInt</a>(|V|, 32, "<code>unsigned</code>").
    1.  Return the IDL {{unsigned long}} value that represents the same numeric value as |x|.
</div>

<p id="unsigned-long-to-es">
    The result of [=converted to an ECMAScript value|converting=]
    an IDL {{unsigned long}} value to an ECMAScript
    value is a Number that
    represents the same numeric value as the IDL
    {{unsigned long}} value.
    The Number value will be an integer in the range [0, 4294967295].
</p>


<h5 id="es-long-long">long long</h5>

<div id="es-to-long-long" algorithm="convert an ECMAScript value to long long">

    An ECMAScript value |V| is [=converted to an IDL value|converted=]
    to an IDL {{long long}} value by running the following algorithm:

    1.  Let |x| be [=?=] <a abstract-op>ConvertToInt</a>(|V|, 64, "<code>signed</code>").
    1.  Return the IDL {{long long}} value that represents the same numeric value as |x|.
</div>

<p id="long-long-to-es">
    The result of [=converted to an ECMAScript value|converting=]
    an IDL {{long long}} value to an ECMAScript
    value is a Number value that
    represents the closest numeric value to the {{long long}},
    choosing the numeric value with an <em>even significand</em> if there are
    two [=equally close values=].
    If the {{long long}} is in the range
    [−2<sup>53</sup> + 1, 2<sup>53</sup> − 1], then the Number
    will be able to represent exactly the same value as the
    {{long long}}.
</p>


<h5 id="es-unsigned-long-long">unsigned long long</h5>

<div id="es-to-unsigned-long-long" algorithm="convert an ECMAScript value to unsigned long long">

    An ECMAScript value |V| is [=converted to an IDL value|converted=]
    to an IDL {{unsigned long long}} value by running the following algorithm:

    1.  Let |x| be [=?=] <a abstract-op>ConvertToInt</a>(|V|, 64, "<code>unsigned</code>").
    1.  Return the IDL {{unsigned long long}} value that represents the same numeric value as |x|.
</div>

<p id="unsigned-long-long-to-es">
    The result of [=converted to an ECMAScript value|converting=]
    an IDL {{unsigned long long}} value to an ECMAScript
    value is a Number value that
    represents the closest numeric value to the {{unsigned long long}},
    choosing the numeric value with an <em>even significand</em> if there are
    two [=equally close values=].
    If the {{unsigned long long}} is less than or equal to 2<sup>53</sup> − 1,
    then the Number will be able to
    represent exactly the same value as the
    {{unsigned long long}}.
</p>

<h5 id="es-integer-types-abstract-ops">Abstract operations</h5>

<div algorithm>

    <dfn lt="IntegerPart" abstract-op>IntegerPart(|n|)</dfn>:

    1.  Let |r| be <a abstract-op>floor</a>(<a abstract-op>abs</a>(|n|)).
    1.  If |n| &lt; 0, then return -1 × |r|.
    1.  Otherwise, return |r|.
</div>

<div algorithm>

    <dfn lt="ConvertToInt" abstract-op>ConvertToInt(|V|, |bitLength|, |signedness|)</dfn>:

    1.  If |bitLength| is 64, then:
        1.  Let |upperBound| be 2<sup>53</sup> − 1.
        1.  If |signedness| is "<code>unsigned</code>", then let |lowerBound| be 0.
        1.  Otherwise let |lowerBound| be −2<sup>53</sup> + 1.

            Note: this ensures {{long long}} types
            [=extended attribute associated with|associated with=] [{{EnforceRange}}] or
            [{{Clamp}}] [=extended attributes=] are representable in ECMAScript's [=Number type=]
            as unambiguous integers.

    1.  Otherwise, if |signedness| is "<code>unsigned</code>", then:
        1.  Let |lowerBound| be 0.
        1.  Let |upperBound| be 2<sup>|bitLength|</sup> − 1.
    1.  Otherwise:
        1.  Let |lowerBound| be -2<sup>|bitLength| − 1</sup>.
        1.  Let |upperBound| be 2<sup>|bitLength| − 1</sup> − 1.
    1.  Let |x| be [=?=] <a abstract-op>ToNumber</a>(|V|).
    1.  If |x| is −0, then set |x| to +0.
    1.  If the conversion is to an IDL type [=extended attribute associated with|associated with=]
        the [{{EnforceRange}}] [=extended attribute=], then:
        1.  If |x| is <emu-val>NaN</emu-val>, +∞, or −∞,
            then [=ECMAScript/throw=] a {{ECMAScript/TypeError}}.
        1.  Set |x| to [=!=] <a abstract-op>IntegerPart</a>(|x|).
        1.  If |x| &lt; |lowerBound| or |x| &gt; |upperBound|,
            then [=ECMAScript/throw=] a {{ECMAScript/TypeError}}.
        1.  Return |x|.
    1.  If |x| is not <emu-val>NaN</emu-val> and the conversion is to an IDL type
        [=extended attribute associated with|associated with=] the [{{Clamp}}] extended attribute,
        then:
        1.  Set |x| to <a abstract-op>min</a>(<a abstract-op>max</a>(|x|, |lowerBound|), |upperBound|).
        1.  Round |x| to the nearest integer, choosing the even integer if it lies halfway between two,
            and choosing +0 rather than −0.
        1.  Return |x|.
    1.  If |x| is <emu-val>NaN</emu-val>, +0, +∞, or −∞,
        then return +0.
    1.  Set |x| to [=!=] <a abstract-op>IntegerPart</a>(|x|).
    1.  Set |x| to |x| [=modulo=] 2<sup>|bitLength|</sup>.
    1.  If |signedness| is "<code>signed</code>" and |x| ≥ 2<sup>|bitLength| − 1</sup>,
        then return |x| − 2<sup>|bitLength|</sup>.
    1.  Otherwise, return |x|.
</div>


<h4 id="es-float">float</h4>

<div id="es-to-float" algorithm="convert an ECMAScript value to float">

    An ECMAScript value |V| is [=converted to an IDL value|converted=]
    to an IDL {{float}} value by running the following algorithm:

    1.  Let |x| be [=?=] <a abstract-op>ToNumber</a>(|V|).
    1.  If |x| is <emu-val>NaN</emu-val>, +∞, or −∞,
        then [=ECMAScript/throw=] a {{ECMAScript/TypeError}}.
    1.  Let |S| be the set of finite IEEE 754 single-precision floating
        point values except −0, but with two special values added: 2<sup>128</sup> and
        −2<sup>128</sup>.
    1.  Let |y| be the number in |S| that is closest
        to |x|, selecting the number with an
        <em>even significand</em> if there are two [=equally close values=].
        (The two special values 2<sup>128</sup> and −2<sup>128</sup>
        are considered to have even significands for this purpose.)
    1.  If |y| is 2<sup>128</sup> or −2<sup>128</sup>, then [=ECMAScript/throw=] a {{ECMAScript/TypeError}}.
    1.  If |y| is +0 and |x| is negative, return −0.
    1.  Return |y|.
</div>

<p id="float-to-es">
    The result of [=converted to an ECMAScript value|converting=]
    an IDL {{float}} value to an ECMAScript
    value is the Number value that represents the same numeric value as the IDL
    {{float}} value.
</p>


<h4 id="es-unrestricted-float">unrestricted float</h4>

<div id="es-to-unrestricted-float" algorithm="convert an ECMAScript value to unrestricted float">

    An ECMAScript value |V| is [=converted to an IDL value|converted=]
    to an IDL {{unrestricted float}} value by running the following algorithm:

    1.  Let |x| be [=?=] <a abstract-op>ToNumber</a>(|V|).
    1.  If |x| is <emu-val>NaN</emu-val>, then return the IDL {{unrestricted float}} value that represents the IEEE 754 NaN value with the bit pattern 0x7fc00000 [[!IEEE-754]].
    1.  Let |S| be the set of finite IEEE 754 single-precision floating
        point values except −0, but with two special values added: 2<sup>128</sup> and
        −2<sup>128</sup>.
    1.  Let |y| be the number in |S| that is closest
        to |x|, selecting the number with an
        <em>even significand</em> if there are two [=equally close values=].
        (The two special values 2<sup>128</sup> and −2<sup>128</sup>
        are considered to have even significands for this purpose.)
    1.  If |y| is 2<sup>128</sup>, return +∞.
    1.  If |y| is −2<sup>128</sup>, return −∞.
    1.  If |y| is +0 and |x| is negative, return −0.
    1.  Return |y|.
</div>

Note: Since there is only a single ECMAScript <emu-val>NaN</emu-val> value,
it must be canonicalized to a particular single precision IEEE 754 NaN value.  The NaN value
mentioned above is chosen simply because it is the quiet NaN with the lowest
value when its bit pattern is interpreted as an unsigned 32 bit integer.

<div id="unrestricted-float-to-es" algorithm="convert an unrestricted float to an ECMAScript value">

    The result of [=converted to an ECMAScript value|converting=]
    an IDL {{unrestricted float}} value to an ECMAScript
    value is a Number:

    1.  If the IDL {{unrestricted float}} value is a NaN,
        then the Number value is <emu-val>NaN</emu-val>.
    1.  Otherwise, the Number value is
        the one that represents the same numeric value as the IDL
        {{unrestricted float}} value.
</div>


<h4 id="es-double">double</h4>

<div id="es-to-double" algorithm="convert an ECMAScript value to double">

    An ECMAScript value |V| is [=converted to an IDL value|converted=]
    to an IDL {{double}} value by running the following algorithm:

    1.  Let |x| be [=?=] <a abstract-op>ToNumber</a>(|V|).
    1.  If |x| is <emu-val>NaN</emu-val>, +∞, or −∞,
        then [=ECMAScript/throw=] a {{ECMAScript/TypeError}}.
    1.  Return the IDL {{double}} value
        that represents the same numeric value as |x|.
</div>

<p id="double-to-es">
    The result of [=converted to an ECMAScript value|converting=]
    an IDL {{double}} value to an ECMAScript
    value is the Number value that represents the
    same numeric value as the IDL {{double}} value.
</p>


<h4 id="es-unrestricted-double">unrestricted double</h4>

<div id="es-to-unrestricted-double" algorithm="convert an ECMAScript value to unrestricted double">

    An ECMAScript value |V| is [=converted to an IDL value|converted=]
    to an IDL {{unrestricted double}} value by running the following algorithm:

    1.  Let |x| be [=?=] <a abstract-op>ToNumber</a>(|V|).
    1.  If |x| is <emu-val>NaN</emu-val>, then
        return the IDL {{unrestricted double}} value that represents
        the IEEE 754 NaN value with the bit pattern 0x7ff8000000000000 [[!IEEE-754]].
    1.  Return the IDL {{unrestricted double}} value
        that represents the same numeric value as |x|.
</div>

Note: Since there is only a single ECMAScript <emu-val>NaN</emu-val> value,
it must be canonicalized to a particular double precision IEEE 754 NaN value.  The NaN value
mentioned above is chosen simply because it is the quiet NaN with the lowest
value when its bit pattern is interpreted as an unsigned 64 bit integer.

<div id="unrestricted-double-to-es" algorithm="convert an unrestricted double to an ECMAScript value">

    The result of [=converted to an ECMAScript value|converting=]
    an IDL {{unrestricted double}} value to an ECMAScript
    value is a Number:

    1.  If the IDL {{unrestricted double}} value is a NaN,
        then the Number value is <emu-val>NaN</emu-val>.
    1.  Otherwise, the Number value is
        the one that represents the same numeric value as the IDL
        {{unrestricted double}} value.
</div>


<h4 id="es-DOMString">DOMString</h4>

<div id="es-to-DOMString" algorithm="convert an ECMAScript value to DOMString">

    An ECMAScript value |V| is [=converted to an IDL value|converted=]
    to an IDL {{DOMString}} value by running the following algorithm:

    1.  If |V| is <emu-val>null</emu-val> and the conversion is to an IDL type
        [=extended attribute associated with|associated with=] the [{{TreatNullAs}}] extended
        attribute, then return the {{DOMString}} value that represents the empty string.
    1.  Let |x| be <a abstract-op>ToString</a>(|V|).
    1.  Return the IDL {{DOMString}} value that represents the same sequence of code units as the one the ECMAScript String value |x| represents.
</div>

<p id="DOMString-to-es">
    The result of [=converted to an ECMAScript value|converting=]
    an IDL {{DOMString}} value to an ECMAScript
    value is the String
    value that represents the same sequence of [=code units=] that the
    IDL {{DOMString}} represents.
</p>


<h4 id="es-ByteString">ByteString</h4>

<div id="es-to-ByteString" algorithm="convert an ECMAScript value to ByteString">

    An ECMAScript value |V| is [=converted to an IDL value|converted=]
    to an IDL {{ByteString}} value by running the following algorithm:

    1.  Let |x| be <a abstract-op>ToString</a>(|V|).
    1.  If the value of any [=ECMAScript String/element=]
        of |x| is greater than 255, then [=ECMAScript/throw=] a {{ECMAScript/TypeError}}.
    1.  Return an IDL {{ByteString}} value
        whose length is the length of |x|, and where the value of each element is
        the value of the corresponding element of |x|.
</div>

<p id="ByteString-to-es">
    The result of [=converted to an ECMAScript value|converting=]
    an IDL {{ByteString}} value to an ECMAScript
    value is a String
    value whose length is the length of the {{ByteString}},
    and the value of each [=ECMAScript String/element=] of which is the value of the corresponding element
    of the {{ByteString}}.
</p>


<h4 id="es-USVString">USVString</h4>

<div id="es-to-USVString" algorithm="convert an ECMAScript value to USVString">

    An ECMAScript value |V| is [=converted to an IDL value|converted=]
    to an IDL {{USVString}} value by running the following algorithm:

    1.  Let |string| be the result of [=converted to an IDL value|converting=] |V|
        to a {{DOMString}}.
    1.  Return an IDL {{USVString}} value that is the result of
        [=obtain Unicode|converting=] |string| to a sequence of [=Unicode scalar values=].
</div>

<div id="USVString-to-es" algorithm="convert an USVString to an ECMAScript value">

    An IDL {{USVString}} value is [=converted to an ECMAScript value|converted=]
    to an ECMAScript value by running the following algorithm:

    1.  Let |scalarValues| be the sequence of [=Unicode scalar values=] the {{USVString}} represents.
    1.  Let |string| be the sequence of [=code units=] that results from encoding |scalarValues| in UTF-16.
    1.  Return the String value that represents the same sequence of [=code units=] as |string|.
</div>


<h4 id="es-object">object</h4>

IDL {{object}}
values are represented by ECMAScript Object values.

<div id="es-to-object" algorithm="convert an ECMAScript value to object">

    An ECMAScript value |V| is [=converted to an IDL value|converted=]
    to an IDL {{object}} value by running the following algorithm:

    1.  If <a abstract-op>Type</a>(|V|) is not Object, then [=ECMAScript/throw=] a {{ECMAScript/TypeError}}.
    1.  Return the IDL {{object}} value that is a reference to the same object as |V|.
</div>

<p id="object-to-es">
    The result of [=converted to an ECMAScript value|converting=]
    an IDL {{object}} value to an ECMAScript
    value is the Object value that represents a reference to the same object that the
    IDL {{object}} represents.
</p>


<h4 id="es-symbol">symbol</h4>

IDL {{symbol}} values are represented by ECMAScript Symbol values.

<div id="es-to-symbol" algorithm="convert an ECMAScript value to a symbol">
    An ECMAScript value |V| is [=converted to an IDL value|converted=] to an IDL {{symbol}} value
    by running the following algorithm:

    1.  If <a abstract-op>Type</a>(|V|) is not Symbol, then [=ECMAScript/throw=] a {{ECMAScript/TypeError}}.
    1.  Return the IDL {{symbol}} value that is a reference to the same symbol as |V|.
</div>

<p id="symbol-to-es">
    The result of [=converted to an ECMAScript value|converting=] an IDL {{symbol}} value to an
    ECMAScript value is the Symbol value that represents a reference to the same
    symbol that the IDL {{symbol}} represents.
</p>


<h4 id="es-interface">Interface types</h4>

IDL [=interface type=]
values are represented by ECMAScript Object values (including [=function objects=]).

<div id="es-to-interface" algorithm="convert an ECMAScript value to interface">

    An ECMAScript value |V| is [=converted to an IDL value|converted=]
    to an IDL [=interface type=] value by running the following algorithm (where |I| is the [=interface=]):

    1.  If |V| [=implements=] |I|, then return the IDL [=interface type=] value that represents a reference to that platform object.
    1.  [=ECMAScript/Throw=] a {{ECMAScript/TypeError}}.
</div>

<p id="interface-to-es">
    The result of [=converted to an ECMAScript value|converting=]
    an IDL [=interface type=]
    value to an ECMAScript value is the Object
    value that represents a reference to the same object that the IDL
    [=interface type=] value represents.
</p>


<h4 id="es-callback-interface">Callback interface types</h4>

IDL [=callback interface type=]
values are represented by ECMAScript Object values (including [=function objects=]).

<div id="es-to-callback-interface" algorithm="convert an ECMAScript value to callback interface">

    An ECMAScript value |V| is [=converted to an IDL value|converted=]
    to an IDL [=callback interface type=] value by running the following algorithm:

    1.  If <a abstract-op>Type</a>(|V|) is not Object, then [=ECMAScript/throw=] a {{ECMAScript/TypeError}}.
    1.  Return the IDL [=callback interface type=] value that represents a reference to |V|, with
        the [=incumbent settings object=] as the [=callback context=].
</div>

<p id="callback-interface-to-es">
    The result of [=converted to an ECMAScript value|converting=]
    an IDL [=callback interface type=]
    value to an ECMAScript value is the Object
    value that represents a reference to the same object that the IDL
    [=callback interface type=] value represents.
</p>


<h4 id="es-dictionary">Dictionary types</h4>

IDL [=dictionary type=] values are represented
by ECMAScript Object values.  Properties on
the object (or its prototype chain) correspond to [=dictionary members=].

<div id="es-to-dictionary" algorithm="convert an ECMAScript value to dictionary">

    An ECMAScript value |esDict| is [=converted to an IDL value|converted=]
    to an IDL [=dictionary type=] value by
    running the following algorithm (where |D| is the [=dictionary type=]):

    1.  If <a abstract-op>Type</a>(|esDict|) is not Undefined, Null or Object, then [=ECMAScript/throw=] a {{ECMAScript/TypeError}}.
    1.  Let |idlDict| be an empty dictionary value of type |D|;
        every [=dictionary member=]
        is initially considered to be [=not present=].
    1.  Let |dictionaries| be a list consisting of |D| and all of |D|’s [=inherited dictionaries=],
        in order from least to most derived.
    1.  For each dictionary |dictionary| in |dictionaries|, in order:
        1.  For each dictionary member |member| declared on |dictionary|, in lexicographical order:
            1.  Let |key| be the [=identifier=] of |member|.
            1.  Let |esMemberValue| be an ECMAScript value, depending on <a abstract-op>Type</a>(|esDict|):
                <dl class="switch">
                     :  Undefined
                     :  Null
                     :: <emu-val>undefined</emu-val>
                     :  anything else
                     :: [=?=] <a abstract-op>Get</a>(|esDict|, |key|)
                </dl>
            1.  If |esMemberValue| is not <emu-val>undefined</emu-val>, then:
                1.  Let |idlMemberValue| be the result of [=converted to an IDL value|converting=] |esMemberValue| to an IDL value whose type is the type |member| is declared to be of.
                1.  Set the dictionary member on |idlDict| with key name |key| to the value |idlMemberValue|.  This dictionary member is considered to be [=present=].
            1.  Otherwise, if |esMemberValue| is <emu-val>undefined</emu-val> but |member| has a [=dictionary member/default value=], then:
                1.  Let |idlMemberValue| be |member|’s default value.
                1.  Set the dictionary member on |idlDict| with key name |key| to the value |idlMemberValue|.  This dictionary member is considered to be [=present=].
            1.  Otherwise, if |esMemberValue| is
                <emu-val>undefined</emu-val> and |member| is a
                [=required dictionary member=], then throw a {{ECMAScript/TypeError}}.
    1.  Return |idlDict|.
</div>

Note: The order that [=dictionary members=] are looked
up on the ECMAScript object are not necessarily the same as the object’s property enumeration order.

<div id="dictionary-to-es" algorithm="convert a dictionary to an ECMAScript value">

    An IDL dictionary value |V| is [=converted to an ECMAScript value|converted=]
    to an ECMAScript Object value by
    running the following algorithm (where |D| is the [=dictionary=]):

    1.  Let |O| be [=!=] <a abstract-op>ObjectCreate</a>({{%ObjectPrototype%}}).
    1.  Let |dictionaries| be a list consisting of |D| and all of |D|’s [=inherited dictionaries=],
        in order from least to most derived.
    1.  For each dictionary |dictionary| in |dictionaries|, in order:
        1.  For each dictionary member |member| declared on |dictionary|, in lexicographical order:
            1.  Let |key| be the [=identifier=] of |member|.
            1.  If the dictionary member named |key| is [=present=] in |V|, then:
                1.  Let |idlValue| be the value of |member| on |V|.
                1.  Let |value| be the result of [=converted to an ECMAScript value|converting=] |idlValue| to an ECMAScript value.
                1.  Perform [=!=] <a abstract-op>CreateDataProperty</a>(|O|, |key|, |value|).
    1.  Return |O|.
</div>


<h4 id="es-enumeration">Enumeration types</h4>

IDL [=enumeration types=] are represented by ECMAScript String
values.

<div id="es-to-enumeration" algorithm="convert an ECMAScript value to enumeration">

    An ECMAScript value |V| is [=converted to an IDL value|converted=]
    to an IDL [=enumeration|enumeration type=] value as follows
    (where |E| is the [=enumeration=]):

    1.  Let |S| be the result of calling <a abstract-op>ToString</a>(|V|).
    1.  If |S| is not one of |E|’s [=enumeration values=],
        then [=ECMAScript/throw=] a {{ECMAScript/TypeError}}.
    1.  Return the enumeration value of type |E| that is equal to |S|.
</div>

<p id="enumeration-to-es">
    The result of [=converted to an ECMAScript value|converting=]
    an IDL [=enumeration|enumeration type=] value to an ECMAScript
    value is the String
    value that represents the same sequence of [=code units=] as
    the [=enumeration value=].
</p>


<h4 id="es-callback-function">Callback function types</h4>

IDL [=callback function types=] are represented by ECMAScript [=function objects=], except in the
[{{TreatNonObjectAsNull}}] case, when they can be any object.

<div id="es-to-callback-function" algorithm="convert an ECMAScript value to callback function">

    An ECMAScript value |V| is [=converted to an IDL value|converted=]
    to an IDL [=callback function type=] value by running the following algorithm:

    1.  If the result of calling <a abstract-op>IsCallable</a>(|V|) is <emu-val>false</emu-val>
        and the conversion to an IDL value
        is not being performed due
        to |V| being assigned to an [=attribute=]
        whose type is a [=nullable type|nullable=]
        [=callback function=]
        that is annotated with [{{TreatNonObjectAsNull}}],
        then [=ECMAScript/throw=] a {{ECMAScript/TypeError}}.
    1.  Return the IDL [=callback function type=] value
        that represents a reference to the same object that |V| represents, with the
        [=incumbent settings object=] as the [=callback context=].
</div>

<p id="callback-function-to-es">
    The result of [=converted to an ECMAScript value|converting=]
    an IDL [=callback function type=]
    value to an ECMAScript value is a reference to the same object
    that the IDL [=callback function type=] value represents.
</p>


<h4 id="es-nullable-type">Nullable types — |T|?</h4>

IDL [=nullable type=] values are represented
by values of either the ECMAScript type corresponding to the [=nullable types/inner type|inner IDL type=], or
the ECMAScript <emu-val>null</emu-val> value.

<div id="es-to-nullable" algorithm="convert an ECMAScript value to nullable">

    An ECMAScript value |V| is [=converted to an IDL value|converted=]
    to an IDL [=nullable type=] <code class="idl">|T|?</code>
    value (where |T| is the [=nullable types/inner type=]) as follows:

    1.  If <a abstract-op>Type</a>(|V|) is not Object, and
        the conversion to an IDL value is being performed due
        to |V| being assigned to an [=attribute=]
        whose type is a [=nullable type|nullable=]
        [=callback function=]
        that is annotated with [{{TreatNonObjectAsNull}}],
        then return the IDL
        [=nullable type=] <code class="idl">|T|?</code>
        value <emu-val>null</emu-val>.
    1.  Otherwise, if |V| is <emu-val>null</emu-val> or <emu-val>undefined</emu-val>, then return the IDL
        [=nullable type=] <code class="idl">|T|?</code>
        value <emu-val>null</emu-val>.
    1.  Otherwise, return the result of
        [=converted to an IDL value|converting=] |V|
        using the rules for the [=nullable types/inner type|inner IDL type=] <code class="idl">T</code>.
</div>

<div id="nullable-to-es" algorithm="convert a nullable to an ECMAScript value">

    The result of [=converted to an ECMAScript value|converting=]
    an IDL [=nullable type=] value to an ECMAScript value is:

    1.  If the IDL [=nullable type=] <code class="idl">|T|?</code>
        value is <emu-val>null</emu-val>,
        then the ECMAScript value is <emu-val>null</emu-val>.
    1.  Otherwise, the ECMAScript value is the result of
        [=converted to an ECMAScript value|converting=]
        the IDL [=nullable type=] value
        to the [=nullable types/inner type|inner IDL type=] <code class="idl">|T|</code>.
</div>

<h4 id="es-sequence">Sequences — sequence&lt;|T|&gt;</h4>

IDL <a lt="sequence type">sequence&lt;|T|&gt;</a> values are represented by
ECMAScript Array values.

<div id="es-to-sequence" algorithm="convert an ECMAScript value to sequence">

    An ECMAScript value |V| is [=converted to an IDL value|converted=]
    to an IDL <a lt="sequence type">sequence&lt;<var ignore>T</var>&gt;</a> value as follows:

    1.  If <a abstract-op>Type</a>(|V|) is not Object,
        [=ECMAScript/throw=] a {{ECMAScript/TypeError}}.
    1.  Let |method| be [=?=] <a abstract-op>GetMethod</a>(|V|, {{@@iterator}}).
    1.  If |method| is <emu-val>undefined</emu-val>,
        [=ECMAScript/throw=] a {{ECMAScript/TypeError}}.
    1.  Return the result of [=creating a sequence from an iterable|creating a sequence=]
        from |V| and |method|.
</div>

<div id="sequence-to-es" algorithm="convert a sequence to an ECMAScript value">

    An IDL sequence value |S| of type
    <a lt="sequence type">sequence&lt;<var ignore>T</var>&gt;</a> is
    [=converted to an ECMAScript value|converted=]
    to an ECMAScript Array object as follows:


    1.  Let |n| be the length of |S|.
    1.  Let |A| be a new Array object created as if by the expression <code>[]</code>.
    1.  Initialize |i| to be 0.
    1.  While |i| &lt; |n|:
        1.  Let |V| be the value in |S| at index |i|.
        1.  Let |E| be the result of [=converted to an ECMAScript value|converting=]
            |V| to an ECMAScript value.
        1.  Let |P| be the result of calling <a abstract-op>ToString</a>(|i|).
        1.  Call <a abstract-op>CreateDataProperty</a>(|A|, |P|, |E|).
        1.  Set |i| to |i| + 1.
    1.  Return |A|.
</div>


<h5 id="create-sequence-from-iterable" dfn>Creating a sequence from an iterable</h5>

<div algorithm="create sequence from iterable">

    To create an IDL value of type <a lt="sequence type">sequence&lt;|T|&gt;</a>
    given an iterable |iterable| and an iterator getter |method|,
    perform the following steps:

    1.  Let |iter| be [=?=] <a abstract-op>GetIterator</a>(|iterable|, <emu-const>sync</emu-const>, |method|).
    1.  Initialize |i| to be 0.
    1.  Repeat
        1.  Let |next| be [=?=] <a abstract-op>IteratorStep</a>(|iter|).
        1.  If |next| is <emu-val>false</emu-val>,
            then return an IDL sequence value of type
            <a lt="sequence type">sequence&lt;|T|&gt;</a>
            of length |i|, where the value of the element
            at index |j| is
            |S|<sub>|j|</sub>.
        1.  Let |nextItem| be [=?=] <a abstract-op>IteratorValue</a>(|next|).
        1.  Initialize |S|<sub>|i|</sub> to the result of
            [=converted to an IDL value|converting=]
            |nextItem| to an IDL value of type |T|.
        1.  Set |i| to |i| + 1.
</div>

<div class="example">

    The following [=interface=] defines
    an [=attribute=] of a sequence
    type as well as an [=operation=]
    with an argument of a sequence type.

    <pre highlight="webidl">
        [Exposed=Window]
        interface Canvas {

          sequence&lt;DOMString&gt; getSupportedImageCodecs();

          void drawPolygon(sequence&lt;double&gt; coordinates);
          sequence&lt;double&gt; getLastDrawnPolygon();

          // ...
        };
    </pre>

    In an ECMAScript implementation of this interface, an Array
    object with elements of type String is used to
    represent a <code class="idl">sequence&lt;DOMString&gt;</code>, while an
    Array with elements of type Number
    represents a <code class="idl">sequence&lt;double&gt;</code>.  The
    Array objects are effectively passed by
    value; every time the <code>getSupportedImageCodecs()</code>
    function is called a new Array is
    returned, and whenever an Array is
    passed to <code>drawPolygon</code> no reference
    will be kept after the call completes.

        <pre highlight="js">
        // Obtain an instance of Canvas.  Assume that getSupportedImageCodecs()
        // returns a sequence with two DOMString values: "image/png" and "image/svg+xml".
        var canvas = getCanvas();

        // An Array object of length 2.
        var supportedImageCodecs = canvas.getSupportedImageCodecs();

        // Evaluates to "image/png".
        supportedImageCodecs[0];

        // Each time canvas.getSupportedImageCodecs() is called, it returns a
        // new Array object.  Thus modifying the returned Array will not
        // affect the value returned from a subsequent call to the function.
        supportedImageCodecs[0] = "image/jpeg";

        // Evaluates to "image/png".
        canvas.getSupportedImageCodecs()[0];

        // This evaluates to false, since a new Array object is returned each call.
        canvas.getSupportedImageCodecs() == canvas.getSupportedImageCodecs();

        // An Array of Numbers...
        var a = [0, 0, 100, 0, 50, 62.5];

        // ...can be passed to a platform object expecting a sequence&lt;double&gt;.
        canvas.drawPolygon(a);

        // Each element will be converted to a double by first calling ToNumber().
        // So the following call is equivalent to the previous one, except that
        // "hi" will be alerted before drawPolygon() returns.
        a = [false, '',
             { valueOf: function() { alert('hi'); return 100; } }, 0,
             '50', new Number(62.5)];
        canvas.drawPolygon(a);

        // Modifying an Array that was passed to drawPolygon() is guaranteed not to
        // have an effect on the Canvas, since the Array is effectively passed by value.
        a[4] = 20;
        var b = canvas.getLastDrawnPolygon();
        alert(b[4]);    // This would alert "50".
    </pre>
</div>


<h4 id="es-record">Records — record&lt;|K|, |V|&gt;</h4>

IDL [=record=]&lt;|K|, |V|&gt; values are represented by
ECMAScript Object values.

<div id="es-to-record" algorithm="convert an ECMAScript value to record">

    An ECMAScript value |O| is [=converted to an IDL value|converted=]
    to an IDL <code>[=record=]&lt;|K|, |V|></code> value as follows:

    1.  If <a abstract-op>Type</a>(|O|) is not Object,
        [=ECMAScript/throw=] a {{ECMAScript/TypeError}}.
    1.  Let |result| be a new empty instance of <code>[=record=]&lt;|K|, |V|></code>.
    1.  Let |keys| be [=?=] |O|.\[[OwnPropertyKeys]]().
    1.  [=list/For each=] |key| of |keys|:
        1.  Let |desc| be [=?=] |O|.\[[GetOwnProperty]](|key|).
        1.  If |desc| is not <emu-val>undefined</emu-val>
            and |desc|.\[[Enumerable]] is <emu-val>true</emu-val>:
            1.  Let |typedKey| be |key| [=converted to an IDL value=] of type |K|.
            1.  Let |value| be [=?=] <a abstract-op>Get</a>(|O|, |key|).
            1.  Let |typedValue| be |value| [=converted to an IDL value=] of type |V|.
            1.  [=map/Set=] |result|[|typedKey|] to |typedValue|.

                Note: it's possible that |typedKey| is already in |result|, if |O| is a proxy
                object.
    1.  Return |result|.
</div>

<div id="record-to-es" algorithm="convert a record to an ECMAScript value">

    An IDL <code>[=record=]&lt;…></code> value |D| is
    [=converted to an ECMAScript value|converted=]
    to an ECMAScript value as follows:

    1.  Let |result| be [=!=] <a abstract-op>ObjectCreate</a>({{%ObjectPrototype%}}).
    1.  [=map/For each=] |key| → |value| of |D|:
        1.  Let |esKey| be |key| [=converted to an ECMAScript value=].
        1.  Let |esValue| be |value| [=converted to an ECMAScript value=].
        1.  Let |created| be [=!=] <a abstract-op>CreateDataProperty</a>(|result|, |esKey|, |esValue|).
        1.  Assert: |created| is <emu-val>true</emu-val>.
    1.  Return |result|.
</div>

<div class="example" id="example-es-record">

    Passing the ECMAScript value <code>{b: 3, a: 4}</code> as a
    <code>[=record=]&lt;DOMString, double></code> argument
    would result in the IDL value «[ "<code>b</code>" → 3, "<code>a</code>" → 4 ]».

    Records only consider [=own property|own=] [=enumerable=]
    properties, so given an IDL operation
    <code>record&lt;DOMString, double>
    identity(record&lt;DOMString, double> arg)</code> which returns its
    argument, the following code passes its assertions:

    <pre highlight="js">
        let proto = {a: 3, b: 4};
        let obj = {__proto__: proto, d: 5, c: 6}
        Object.defineProperty(obj, "e", {value: 7, enumerable: false});
        let result = identity(obj);
        console.assert(result.a === undefined);
        console.assert(result.b === undefined);
        console.assert(result.e === undefined);
        let entries = Object.entries(result);
        console.assert(entries[0][0] === "d");
        console.assert(entries[0][1] === 5);
        console.assert(entries[1][0] === "c");
        console.assert(entries[1][1] === 6);
    </pre>

    Record keys and values can be constrained, although keys can only be
    constrained among the three string types.
    The following conversions have the described results:
    <table class="data">
        <thead><th>Value</th><th>Passed to type</th><th>Result</th></thead>
        <tr>
            <td><code>{"😞": 1}</code></td>
            <td><code>[=record=]&lt;ByteString, double></code></td>
            <td>{{ECMAScript/TypeError}}</td>
        </tr>
        <tr>
            <td><code>{"\uD83D": 1}</code></td>
            <td><code>[=record=]&lt;USVString, double></code></td>
            <td>«[ "<code>\uFFFD</code>" → 1 ]»</td>
        </tr>
        <tr>
            <td><code>{"\uD83D": {hello: "world"}}</code></td>
            <td><code>[=record=]&lt;DOMString, double></code></td>
            <td>«[ "<code>\uD83D</code>" → 0 ]»</td>
        </tr>
    </table>
</div>


<h4 id="es-promise">Promise types — Promise&lt;|T|&gt;</h4>

IDL [=promise type=] values are represented by ECMAScript [=PromiseCapability=] records.

<div id="es-to-promise" algorithm="convert an ECMAScript value to promise">

    An ECMAScript value |V| is [=converted to an IDL value|converted=] to an IDL
    <code><a interface>Promise</a>&lt;<var ignore>T</var>></code> value as follows:

    1.  Let |promiseCapability| be [=?=] [$NewPromiseCapability$]({{%Promise%}}).
    1.  Perform [=?=] [$Call$](|promiseCapability|.\[[Resolve]], <emu-val>undefined</emu-val>,
        « |V| »).
    1.  Return |promiseCapability|.
</div>

<p id="promise-to-es">
    The result of [=converted to an ECMAScript value|converting=]
    an IDL [=promise type=] value to an ECMAScript
    value is the value of the \[[Promise]] field of the record that
    IDL [=promise type=] represents.
</p>

<h5 id="es-promise-manipulation">Creating and manipulating Promises</h5>

<div algorithm>

    To <dfn export lt="a new promise">create</dfn> a new
    <code><a interface>Promise</a>&lt;<var ignore>T</var>&gt;</code> in a [=Realm=] |realm|,
    perform the following steps:

    1.  Let |constructor| be |realm|.\[[Intrinsics]].[[{{%Promise%}}]].
    1.  Return [=?=] [$NewPromiseCapability$](|constructor|).
</div>

<div algorithm>

    To create a <dfn export lt="a promise resolved with">resolved promise</dfn> of type
    <code><a interface>Promise</a>&lt;|T|&gt;</code>, with |x| (a value of type |T|) in a [=Realm=]
    |realm|, perform the following steps:

    1.  Let |value| be the result of [=converted to an ECMAScript value|converting=] |x| to an
        ECMAScript value.
    1.  Let |constructor| be |realm|.\[[Intrinsics]].[[{{%Promise%}}]].
    1.  Let |promiseCapability| be [=?=] [$NewPromiseCapability$](|constructor|).
    1.  Perform [=!=] [$Call$](|promiseCapability|.\[[Resolve]], <emu-val>undefined</emu-val>,
        « |value| »).
    1.  Return |promiseCapability|.
</div>

<div algorithm>

    To create a <dfn export lt="a promise rejected with">rejected promise</dfn> of type
    <code><a interface>Promise</a>&lt;<var ignore>T</var>&gt;</code>, with reason |r| (an
    ECMAScript value) in a [=Realm=] |realm|, perform the following steps:

    1.  Let |constructor| be |realm|.\[[Intrinsics]].[[{{%Promise%}}]].
    1.  Let |promiseCapability| be [=?=] [$NewPromiseCapability$](|constructor|).
    1.  Perform [=!=] [$Call$](|promiseCapability|.\[[Reject]], <emu-val>undefined</emu-val>,
        « |r| »).
    1.  Return |promiseCapability|.
</div>

<div algorithm>

    To <dfn export>resolve</dfn> a <code><a interface>Promise</a>&lt;|T|&gt;</code> |p| with |x| (a
    value of type |T|), perform the following steps:

    1.  If |x| is not given, then let it be the {{void}} value.
    1.  Let |value| be the result of [=converted to an ECMAScript value|converting=] |x| to an
        ECMAScript value.
    1.  Perform [=!=] [$Call$](|p|.\[[Resolve]], <emu-val>undefined</emu-val>, « |value| »).

    If |T| is {{void}}, then the |x| argument is optional, allowing a simpler "[=resolve=] p" usage.
</div>

<div algorithm>

    To <dfn export>reject</dfn> a <code><a interface>Promise</a>&lt;<var ignore>T</var>&gt;</code>
    |p| with reason |r| (an ECMAScript value), perform the following steps:

    1.  Perform [=!=] [$Call$](|p|.\[[Reject]], <emu-val>undefined</emu-val>, « |r| »).
</div>

<div algorithm>

    To <dfn id="dfn-perform-steps-once-promise-is-settled" export lt="react|reacting" for="promise">react</dfn>
    to a <code><a interface>Promise</a>&lt;|T|&gt;</code> |promise|, given one or two sets of steps
    to perform, covering when the promise is fulfilled, rejected, or both, perform the following
    steps:

    1.  Let |onFulfilledSteps| be the following steps given argument |V|:
        1.  Let |value| be the result of [=converted to an IDL value|converting=] |V| to an IDL
            value of type |T|.
        1.  If there are no steps that are required to be run if the promise was fulfilled, then
            return <emu-val>undefined</emu-val>.
        1.  Let |result| be the result of performing any steps that were required to be run if
            the promise was fulfilled, given |value| if |T| is not {{void}}.
        1.  Return |result|, [=converted to an ECMAScript value=].
    1.  Let |onFulfilled| be [=!=] [$CreateBuiltinFunction$](|onFulfilledSteps|, « »):
    1.  Let |onRejectedSteps| be the following steps given argument |R|:
        1.  Let |reason| be the result of [=converted to an IDL value|converting=]
            |R| to an IDL value of type {{any}}.
        1.  If there are no steps that are required to be run if the promise was rejected, then
            return <emu-val>undefined</emu-val>.
        1.  Let |result| be the result of performing any steps that were required to be run if the
            promise was rejected, given |reason|.
        1.  Return |result|, [=converted to an ECMAScript value=].
    1.  Let |onRejected| be [=!=] [$CreateBuiltinFunction$](|onRejectedSteps|, « »):
    1.  Let |constructor| be |promise|.\[[Promise]].\[[Realm]].\[[Intrinsics]].[[{{%Promise%}}]].
    1.  Let |newCapability| be [=?=] [$NewPromiseCapability$](|constructor|).

        Note: Not all callers will use the returned {{Promise}}. Implementations might wish to
        avoid creating |newCapability| in those cases.
    1.  Return [=!=] [$PerformPromiseThen$](|promise|.\[[Promise]], |onFulfilled|, |onRejected|,
        |newCapability|).

    Note: This algorithm will behave in a very similar way to the
    {{%PromiseProto_then%|Promise.then()}} method.
    In particular, if the steps return a value of type |U| or
    <code><a interface>Promise</a>&lt;|U|&gt;</code>, this algorithm returns a
    <code><a interface>Promise</a>&lt;|U|&gt;</code> as well.
</div>

<div algorithm>

    To perform some steps <dfn export>upon fulfillment</dfn> of a
    <code><a interface>Promise</a>&lt;|T|&gt;</code> |promise| given some steps |steps| taking a
    value of type |T|, perform the following steps:

    1.  [=promise/React=] to |promise|:
        *   If |promise| was fulfilled with value |v|, then:
            1.  Perform |steps| with |v|.
</div>

<div algorithm>

    To perform some steps <dfn export>upon rejection</dfn> of a
    <code><a interface>Promise</a>&lt;<var ignore>T</var>&gt;</code> |promise| given some steps
    |steps| taking an ECMAScript value, perform the following steps:

    1.  [=promise/React=] to |promise|:
        *   If |promise| was rejected with reason |r|, then:
            1.  Perform |steps| with |r|.
</div>

<div algorithm>

    To <dfn export lt="wait for all|waiting for all">wait for all</dfn> with a [=list=] of
    <code><a interface>Promise</a>&lt;|T|&gt;</code> values |promises|, with success steps
    |successSteps| that take a [=list=] of |T| values and failure steps |failureSteps| that take a
    rejection reason {{any}} value, perform the following steps:

    1.  Let |fullfilledCount| be 0.
    1.  Let |rejected| be false.
    1.  Let |rejectionHandlerSteps| be the following steps given |arg|:
        1.  If |rejected| is true, abort these steps.
        1.  Set |rejected| to true.
        1.  Perform |failureSteps| given |arg|.
    1.  Let |rejectionHandler| be [=!=] [$CreateBuiltinFunction$](|rejectionHandlerSteps|, « »):
    1.  Let |total| be |promises|'s [=list/size=].
    1.  If |total| is 0, then:
        1.  [=Queue a microtask=] to perform |successSteps| given « ».
        1.  Return.
    1.  Let |index| be 0.
    1.  Let |result| be a [=list=] containing |total| null values.
    1.  [=list/For each=] |promise| of |promises|:
        1.  Let |promiseIndex| be |index|.
        1.  Let |fulfillmentHandler| be the following steps given |arg|:
            1.  Set |result|[|promiseIndex|] to |arg|.
            1.  Set |fullfilledCount| to |fullfilledCount| + 1.
            1.  If |fullfilledCount| equals |total|, then perform |successSteps| given |result|.
        1.  Let |fulfillmentHandler| be [=!=] [$CreateBuiltinFunction$](|fulfillmentHandler|, « »):
        1.  Perform [$PerformPromiseThen$](|promise|, |fulfillmentHandler|, |rejectionHandler|).
        1.  Set |index| to |index| + 1.
</div>

<div algorithm>

    To
    <dfn id="waiting-for-all-promise" export lt="get a promise to wait for all|getting a promise to wait for all">get a promise for waiting for all</dfn>
    with a [=list=] of <code><a interface>Promise</a>&lt;|T|&gt;</code> values |promises| and a
    [=Realm=] |realm|, perform the following steps:

    1.  Let |promise| be [=a new promise=] of type
        <code><a interface>Promise</a>&lt;<a lt="sequence type">sequence</a>&lt;|T|>></code> in
        |realm|.
    1.  Let |successSteps| be the following steps, given |results|:
        1.  [=Resolve=] |promise| with |results|.
    1.  Let |failureSteps| be the following steps, given |reason|:
        1.  [=Reject=] |promise| with |reason|.
    1.  [=Wait for all=] with |promises|, given |successSteps| and |failureSteps|.
    1.  Return |promise|.
</div>

This phrase is useful when you wish to aggregate the results of multiple promises, and then produce
another promise from them, in the same way that {{Promise/all()|Promise.all()}} functions for
JavaScript code.


<h5 id="es-promise-examples">Examples</h5>

<div class="example" id="promise-example-delay">

    <code>delay</code> is an [=operation=] that returns a promise that will be fulfilled in a
    number of milliseconds.
    It illustrates how simply you can resolve a promise, with one line of prose.

    <pre highlight="webidl">
        interface I {
          Promise&lt;void> delay(unrestricted double ms);
        };
    </pre>

<div algorithm="delay">

    The <code>delay(|ms|)</code> method steps are:

    1.  Let |realm| be <b>this</b>'s [=relevant Realm=].
    1.  If |ms| is NaN, let |ms| be +0; otherwise let |ms| be the maximum of |ms| and +0.
    1.  Let |p| be [=a new promise=] in |realm|.
    1.  Run the following steps [=in parallel=]:
        1.  Wait |ms| milliseconds.
        1.  [=Resolve=] |p|.
    1.  Return |p|.
</div>
</div>

<div class="example" id="promise-example-validatedDelay">

    The <code>validatedDelay</code> [=operation=] is much like <a href="#promise-example-delay">the
    <code>delay</code> function</a>, except it will validate its arguments.
    This shows how to use rejected promises to signal immediate failure before even starting any
    asynchronous operations.

    <pre highlight="webidl">
        interface I {
          Promise&lt;void> validatedDelay(unrestricted double ms);
        };
    </pre>

<div algorithm="validatedDelay">

    The <code>validatedDelay(|ms|)</code> method steps are:

    1.  Let |realm| be <b>this</b>'s [=relevant Realm=].
    1.  If |ms| is NaN, return [=a promise rejected with=] a {{TypeError}} in |realm|.
    1.  If |ms| &lt; 0, return [=a promise rejected with=] a {{RangeError}} in |realm|.
    1.  Let |p| be [=a new promise=] in |realm|.
    1.  Run the following steps [=in parallel=]:
        1.  Wait |ms| milliseconds.
        1.  [=Resolve=] |p|.
    1.  Return |p|.
</div>
</div>

<div class="example" id="promise-example-addDelay">

    <code>addDelay</code> is an [=operation=] that adds an extra number of milliseconds of delay
    between |promise| settling and the returned promise settling.

    <pre highlight="webidl">
        interface I {
          Promise&lt;any> addDelay(Promise&lt;any> promise, unrestricted double ms);
        };
    </pre>

<div algorithm="addDelay">

    The <code>addDelay(|ms|, |promise|)</code> method steps are:

    1.  Let |realm| be <b>this</b>'s [=relevant Realm=].
    1.  Let |taskSource| be some appropriate [=task source=].
    1.  If |ms| is NaN, let |ms| be +0; otherwise let |ms| be the maximum of |ms| and +0.
    1.  Let |p| be [=a new promise=] in |realm|.
    1.  [=promise/React=] to |promise|:
        *   If |promise| was fulfilled with value |v|, then:
            1.  Run the following steps [=in parallel=]:
                1.  Wait |ms| milliseconds.
                1.  [=Queue a task=] to run the following steps on |taskSource|:
                    1.  [=Resolve=] |p| with |v|.
        *   If |promise| was rejected with reason |r|, then:
            1.  Run the following steps [=in parallel=]:
                1.  Wait |ms| milliseconds.
                1.  [=Queue a task=] to run the following steps on |taskSource|:
                    1.  [=Reject=] |p| with |r|.
    1.  Return |p|.
</div>
</div>

<div class="example" id="promise-example-environment-ready" noexport>

    <code>environment.ready</code> is an [=attribute=] that signals when some part of some
    environment, e.g. a DOM document, becomes "ready".
    It illustrates how to encode environmental asynchronicity.

    <pre highlight="webidl">
        interface Environment {
          readonly attribute Promise&lt;void> ready;
        };
    </pre>

    Every <code>Environment</code> object must have a <dfn for="Environment">ready promise</dfn>,
    which is a <code><a interface>Promise</a>&lt;<a interface>void</a>></code>.

<div algorithm="Environment-ready">

    The <code>ready</code> attribute getter steps are:

    1. Return <b>this</b>'s [=Environment/ready promise=].
</div>

<div algorithm="Environment-create">

    To create an <code>Environment</code> object in a [=Realm=] |realm|, perform the following
    steps:

    1.  Let |environment| be [=new=] <code>Environment</code> object in |realm|.
    1.  Set |environment|'s [=Environment/ready promise=] to [=a new promise=] in |realm|.
    1.  Run the following steps [=in parallel=]:
        1.  Do some asynchronous work.
        1.  If |environment| becomes ready successfully, [=resolve=] |environment|'s
            [=Environment/ready promise=].
        1.  If |environment| fails to become ready, [=reject=] |environment|'s
            [=Environment/ready promise=] with a "{{NetworkError!!exception}}" {{DOMException}}.
    1.  Return |environment|.
</div>
</div>

<div class="example" id="promise-example-addBookmark">

    <code>addBookmark</code> is an [=operation=] that requests that the user add the current web
    page as a bookmark.
    It's drawn from <a href="https://github.com/domenic/promises-unwrapping/issues/85">some
    iterative design work</a> and illustrates a more real-world scenario of appealing to
    environmental asynchrony, as well as immediate rejections.

    <pre highlight="webidl">
        interface I {
          Promise&lt;void> addBookmark();
        };
    </pre>

<div algorithm="addBookmark">

    The <code>addBookmark()</code> method steps are:

    1.  If this method was not invoked as a result of explicit user action, return
        [=a promise rejected with=] a "{{SecurityError}}" {{DOMException}}.
    1.  If the document's mode of operation is standalone, return [=a promise rejected with=] a
        "{{NotSupportedError}}" {{DOMException}}.
    1.  Let |promise| be [=a new promise=].
    1.  Let |info| be the result of getting a web application's metadata.
    1.  Run the following steps [=in parallel=]:
        1.  Using |info|, and in a manner that is user-agent specific, allow the end user to make a
            choice as to whether they want to add the bookmark.
            1.  If the end-user aborts the request to add the bookmark (e.g., they hit escape, or
                press a "cancel" button), [=reject=] |promise| with an "{{AbortError}}"
                {{DOMException}}.
            1.  Otherwise, [=resolve=] |promise|.
    1. Return |promise|.
</div>
</div>

<div class="example" id="promise-example-batchRequest">

    Several places in [[SERVICE-WORKERS]] use [=get a promise to wait for all=].
    <code>batchRequest</code> illustrates a simplified version of one of their uses.
    It takes as input a [=sequence=] of URLs, and returns a promise for a [=sequence=] of
    {{Response}} objects created by fetching the corresponding URL.
    If any of the fetches fail, it will return [=a promise rejected with=] that failure.

    <pre highlight="webidl">
        interface I {
          Promise&lt;sequence&lt;Response>> batchRequest(sequence&lt;USVString> urls);
        };
    </pre>

<div algorithm="batchRequest">

    The <code>batchRequest(|urls|)</code> method steps are:

    1.  Let |responsePromises| be « ».
    1.  [=list/For each=] |url| of |urls|:
        1.  Let |p| be the result of calling {{WindowOrWorkerGlobalScope/fetch()}} with |url|.
        1.  [=list/Append=] |p| to |responsePromises|.
    1.  Let |p| be the result of [=getting a promise to wait for all=] with |responsePromises|.
    1.  Return |p|.
</div>
</div>


<h4 id="es-union">Union types</h4>

IDL [=union type=] values are represented by ECMAScript values
that correspond to the union’s [=member types=].

<div id="es-to-union" algorithm="convert an ECMAScript value to union">

    To [=converted to an IDL value|convert an ECMAScript value=] |V| to an IDL [=union type=]
    value is done as follows:

    1.  If the [=union type=]
        [=includes a nullable type=] and
        |V| is <emu-val>null</emu-val> or <emu-val>undefined</emu-val>,
        then return the IDL value <emu-val>null</emu-val>.
    1.  Let |types| be the [=flattened member types=]
        of the [=union type=].
    1.  If |V| is <emu-val>null</emu-val> or <emu-val>undefined</emu-val>, then:
        1.  If |types| includes a [=dictionary type=], then return the
            result of [=converted to an IDL value|converting=] |V| to that dictionary type.
    1.  If |V| [=is a platform object=], then:
        1.  If |types| includes an [=interface type=] that |V|
            [=implements=], then return the IDL value that is a reference to the object |V|.
        1.  If |types| includes {{object}}, then return the IDL value
            that is a reference to the object |V|.
    1.  If <a abstract-op>Type</a>(|V|) is Object and |V| has an \[[ArrayBufferData]] [=internal slot=], then:
        1.  If |types| includes {{ArrayBuffer}}, then return the
            result of [=converted to an IDL value|converting=]
            |V| to {{ArrayBuffer}}.
        1.  If |types| includes {{object}}, then return the IDL value
            that is a reference to the object |V|.
    1.  If <a abstract-op>Type</a>(|V|) is Object and |V| has a \[[DataView]] [=internal slot=], then:
        1.  If |types| includes {{DataView}}, then return the
            result of [=converted to an IDL value|converting=]
            |V| to {{DataView}}.
        1.  If |types| includes {{object}}, then return the IDL value
            that is a reference to the object |V|.
    1.  If <a abstract-op>Type</a>(|V|) is Object and |V| has a \[[TypedArrayName]] [=internal slot=], then:
        1.  If |types| includes a [=typed array type=]
            whose name is the value of |V|’s \[[TypedArrayName]] [=internal slot=], then return the
            result of [=converted to an IDL value|converting=]
            |V| to that type.
        1.  If |types| includes {{object}}, then return the IDL value
            that is a reference to the object |V|.
    1.  If <a abstract-op>IsCallable</a>(|V|) is true, then:
        1.  If |types| includes a [=callback function=]
            type, then return the result of
            [=converted to an IDL value|converting=]
            |V| to that callback function type.
        1.  If |types| includes {{object}}, then return the IDL value
            that is a reference to the object |V|.
    1.  If <a abstract-op>Type</a>(|V|) is Object, then:
        1.  If |types| includes a [=sequence type=], then
            1.  Let |method| be [=?=] <a abstract-op>GetMethod</a>(|V|, {{@@iterator}}).
            1.  If |method| is not <emu-val>undefined</emu-val>,
                return the result of
                [=creating a sequence from an iterable|creating a sequence=]
                of that type from |V| and |method|.
        1.  If |types| includes a [=frozen array type=], then
            1.  Let |method| be [=?=] <a abstract-op>GetMethod</a>(|V|, {{@@iterator}}).
            1.  If |method| is not <emu-val>undefined</emu-val>,
                return the result of
                [=Creating a frozen array from an iterable|creating a frozen array=]
                of that type from |V| and |method|.
        1.  If |types| includes a [=dictionary type=], then return the
            result of [=converted to an IDL value|converting=]
            |V| to that dictionary type.
        1.  If |types| includes a [=record type=], then return the
            result of [=converted to an IDL value|converting=]
            |V| to that record type.
        1.  If |types| includes a [=callback interface=]
            type, then return the result of
            [=converted to an IDL value|converting=]
            |V| to that [=callback interface type=].
        1.  If |types| includes {{object}}, then return the IDL value
            that is a reference to the object |V|.
    1.  If <a abstract-op>Type</a>(|V|) is Boolean, then:
        1.  If |types| includes a {{boolean}},
            then return the result of [=converted to an IDL value|converting=]
            |V| to {{boolean}}.
    1.  If <a abstract-op>Type</a>(|V|) is Number, then:
        1.  If |types| includes a [=numeric type=],
            then return the result of [=converted to an IDL value|converting=]
            |V| to that [=numeric type=].
    1.  If |types| includes a [=string type=],
        then return the result of
        [=converted to an IDL value|converting=]
        |V| to that type.
    1.  If |types| includes a [=numeric type=],
        then return the result of [=converted to an IDL value|converting=]
        |V| to that [=numeric type=].
    1.  If |types| includes a {{boolean}},
        then return the result of [=converted to an IDL value|converting=]
        |V| to {{boolean}}.
    1.  [=ECMAScript/Throw=] a {{ECMAScript/TypeError}}.
</div>

<p id="union-to-es">
    An IDL union type value is
    [=converted to an ECMAScript value=]
    as follows.  If the value is an {{object}}
    reference to a special object that represents an ECMAScript <emu-val>undefined</emu-val>
    value, then it is converted to the ECMAScript
    <emu-val>undefined</emu-val> value.  Otherwise,
    the rules for converting the [=specific type=]
    of the IDL union type value as described in this section ([[#es-type-mapping]]).
</p>


<h4 id="es-buffer-source-types">Buffer source types</h4>

Values of the IDL [=buffer source types=]
are represented by objects of the corresponding ECMAScript class, with the additional restriction
that unless the type is [=extended attributes associated with|associated with=] the
[{{AllowShared}}] extended attribute, they can only be backed by ECMAScript
{{ECMAScript/ArrayBuffer}} objects, and not {{ECMAScript/SharedArrayBuffer}} objects.

<div id="es-to-buffer-source" algorithm="convert an ECMAScript value to IDL ArrayBuffer">

    An ECMAScript value |V| is [=converted to an IDL value|converted=]
    to an IDL {{ArrayBuffer}} value by running the following algorithm:

    1.  If <a abstract-op>Type</a>(|V|) is not Object,
        or |V| does not have an \[[ArrayBufferData]] [=internal slot=],
        then [=ECMAScript/throw=] a {{ECMAScript/TypeError}}.
    1.  If the conversion is not to an IDL type
        [=extended attributes associated with|associated with=] the [{{AllowShared}}]
        [=extended attribute=], and <a abstract-op>IsSharedArrayBuffer</a>(|V|) is true, then [=ECMAScript/throw=]
        a {{ECMAScript/TypeError}}.
    1.  Return the IDL {{ArrayBuffer}} value that is a reference
        to the same object as |V|.
</div>

<div id="buffer-source-to-es" algorithm="convert an ECMAScript value to IDL DataView">

    An ECMAScript value |V| is [=converted to an IDL value|converted=]
    to an IDL {{DataView}} value by running the following algorithm:

    1.  If <a abstract-op>Type</a>(|V|) is not Object,
        or |V| does not have a \[[DataView]] [=internal slot=],
        then [=ECMAScript/throw=] a {{ECMAScript/TypeError}}.
    1.  If the conversion is not to an IDL type
        [=extended attributes associated with|associated with=] the [{{AllowShared}}]
        [=extended attribute=], and <a abstract-op>IsSharedArrayBuffer</a>(|V|.\[[ViewedArrayBuffer]]) is true,
        then [=ECMAScript/throw=] a {{ECMAScript/TypeError}}.
    1.  Return the IDL {{DataView}} value that is a reference
        to the same object as |V|.
</div>

<div algorithm="convert an ECMAScript value to IDL typed array">

    An ECMAScript value |V| is
    [=converted to an IDL value|converted=]
    to an IDL {{Int8Array}},
    {{Int16Array}},
    {{Int32Array}},
    {{Uint8Array}},
    {{Uint16Array}},
    {{Uint32Array}},
    {{Uint8ClampedArray}},
    {{Float32Array}} or
    {{Float64Array}} value
    by running the following algorithm:

    1.  Let |T| be the IDL type |V| is being converted to.
    1.  Let |typedArrayName| be the [=type name|name=] of |T|'s [=annotated types/inner type=] if
        |T| is an [=annotated type=], or the [=type name|name=] of |T| otherwise.
    1.  If <a abstract-op>Type</a>(|V|) is not Object,
        or |V| does not have a \[[TypedArrayName]] [=internal slot=]
        with a value equal to |typedArrayName|,
        then [=ECMAScript/throw=] a {{ECMAScript/TypeError}}.
    1.  If the conversion is not to an IDL type
        [=extended attributes associated with|associated with=] the [{{AllowShared}}]
        [=extended attribute=], and <a abstract-op>IsSharedArrayBuffer</a>(|V|.\[[ViewedArrayBuffer]]) is true,
        then [=ECMAScript/throw=] a {{ECMAScript/TypeError}}.
    1.  Return the IDL value of type |T| that is a reference to the same object as |V|.
</div>

The result of [=converted to an ECMAScript value|converting=]
an IDL value of any [=buffer source type=]
to an ECMAScript value is the Object value that represents
a reference to the same object that the IDL value represents.

<div algorithm="get a reference to a buffer source">

    When [=get a reference to the buffer source|getting a reference to=]
    or [=get a copy of the buffer source|getting a copy of the bytes held by a buffer source=]
    that is an ECMAScript {{ECMAScript/ArrayBuffer}}, {{ECMAScript/DataView}}
    or typed array object, these steps must be followed:

    1.  Let |O| be the ECMAScript object that is the buffer source.
    1.  Initialize |arrayBuffer| to |O|.
    1.  Initialize |offset| to 0.
    1.  Initialize |length| to 0.
    1.  If |O| has a \[[ViewedArrayBuffer]] [=internal slot=], then:
        1.  Set |arrayBuffer| to the value of |O|’s \[[ViewedArrayBuffer]] [=internal slot=].
        1.  Set |offset| to the value of |O|’s \[[ByteOffset]] [=internal slot=].
        1.  Set |length| to the value of |O|’s \[[ByteLength]] [=internal slot=].
    1.  Otherwise, set |length| to the value of |O|’s \[[ArrayBufferByteLength]] [=internal slot=].
    1.  If <a abstract-op>IsDetachedBuffer</a>(|arrayBuffer|) is <emu-val>true</emu-val>, then
        return the empty byte sequence.
    1.  Let |data| be the value of |O|’s \[[ArrayBufferData]] [=internal slot=].
    1.  Return a reference to or copy of (as required) the |length| bytes in |data|
        starting at byte offset |offset|.
</div>

<div algorithm>

    To <dfn id="dfn-detach" for="ArrayBuffer" export>detach</dfn> an {{ArrayBuffer}}, these steps must be followed:

    1.  Let |O| be the ECMAScript object that is the {{ArrayBuffer}}.
    1.  Perform [=!=] <a abstract-op>DetachArrayBuffer</a>(|O|).
</div>


<h4 id="es-frozen-array">Frozen arrays — FrozenArray&lt;|T|&gt;</h4>

Values of frozen array types are represented by frozen ECMAScript
Array object references.

<div algorithm="convert an ECMAScript value to frozen array">

    An ECMAScript value |V| is [=converted to an IDL value|converted=]
    to an IDL <a interface lt="FrozenArray">FrozenArray&lt;|T|&gt;</a> value
    by running the following algorithm:

    1.  Let |values| be the result of
        [=converted to an IDL value|converting=]
        |V| to IDL type <a lt="sequence type">sequence&lt;|T|&gt;</a>.
    1.  Return the result of
        [=create a frozen array|creating a frozen array=]
        from |values|.
</div>

<div algorithm>

    To <dfn id="dfn-create-frozen-array" export>create a frozen array</dfn>
    from a sequence of values of type |T|, follow these steps:

    1.  Let |array| be the result of
        [=converted to an ECMAScript value|converting=]
        the sequence of values of type |T| to an ECMAScript value.
    1.  Perform <a abstract-op>SetIntegrityLevel</a>(|array|, "<code>frozen</code>").
    1.  Return |array|.
</div>

The result of [=converted to an ECMAScript value|converting=]
an IDL <a interface lt="FrozenArray">FrozenArray&lt;|T|&gt;</a> value to an ECMAScript
value is the Object value that represents a reference
to the same object that the IDL <a interface lt="FrozenArray">FrozenArray&lt;|T|&gt;</a> represents.


<h5 id="create-frozen-array-from-iterable" dfn>Creating a frozen array from an iterable</h5>

<div algorithm="create frozen array from iterable">

    To create an IDL value of type <a interface lt="FrozenArray">FrozenArray&lt;|T|&gt;</a> given an
    iterable |iterable| and an iterator getter |method|, perform the following steps:

    1.  Let |values| be the result of [=creating a sequence from an iterable|creating a sequence=]
        of type <a lt="sequence type">sequence&lt;|T|&gt;</a> from |iterable| and |method|.
    1.  Return the result of [=create a frozen array|creating a frozen array=] from |values|.
</div>


<h3 id="es-extended-attributes">ECMAScript-specific extended attributes</h3>

This section defines a number of
[=extended attributes=]
whose presence affects only the ECMAScript binding.


<h4 id="AllowShared" extended-attribute lt="AllowShared">[AllowShared]</h4>

If the [{{AllowShared}}] [=extended attribute=] appears on one of the [=buffer source types=], it
creates a new IDL type that allows the buffer source type to be backed by an ECMAScript
{{ECMAScript/SharedArrayBuffer}}, instead of only by a non-shared {{ECMAScript/ArrayBuffer}}.

The [{{AllowShared}}] extended attribute must [=takes no arguments|take no arguments=].

A type that is not a [=buffer source type=] must not be
[=extended attributes associated with|associated with=] the [{{AllowShared}}] extended attribute.

See the rules for converting ECMAScript values to IDL [=buffer source types=] in
[[#es-buffer-source-types]] for the specific requirements that the use of [{{AllowShared}}] entails.

<div class="example">
    In the following [=IDL fragment=], one operation's argument uses the [{{AllowShared}}] extended
    attribute, while the other does not:

    <pre highlight="webidl">
        [Exposed=Window]
        interface RenderingContext {
          void readPixels(long width, long height, BufferSource pixels);
          void readPixelsShared(long width, long height, [AllowShared] BufferSource pixels);
        };
    </pre>

    With this definition, a call to <code>readPixels</code> with an {{ECMAScript/SharedArrayBuffer}}
    instance, or any typed array or {{ECMAScript/DataView}} backed by one, will throw a
    {{ECMAScript/TypeError}} exception. In contrast, a call to <code>readPixelsShared</code> will allow such
    objects as input.
</div>


<h4 id="Clamp" extended-attribute lt="Clamp">[Clamp]</h4>

If the [{{Clamp}}] [=extended attribute=] appears on one of the [=integer types=], it creates a new
IDL type such that that when an ECMAScript Number is converted to the IDL type,
out-of-range values will be clamped to the range of valid values, rather than using the operators
that use a modulo operation (<a abstract-op>ToInt32</a>, <a abstract-op>ToUint32</a>, etc.).

The [{{Clamp}}]
extended attribute must
[=takes no arguments|take no arguments=].

A type annotated with the [{{Clamp}}] extended attribute must not appear in a [=read only=]
attribute. A type must not be [=extended attributes associated with|associated with=] both the
[{{Clamp}}] and [{{EnforceRange}}] extended attributes. A type that is not an [=integer type=] must
not be [=extended attributes associated with|associated with=] the [{{Clamp}}] extended attribute.

See the rules for converting ECMAScript values to the various IDL integer
types in [[#es-integer-types]]
for the specific requirements that the use of
[{{Clamp}}] entails.

<div class="example">

    In the following [=IDL fragment=],
    two [=operations=] are declared that
    take three {{octet}} arguments; one uses
    the [{{Clamp}}] [=extended attribute=]
    on all three arguments, while the other does not:

    <pre highlight="webidl">
        [Exposed=Window]
        interface GraphicsContext {
          void setColor(octet red, octet green, octet blue);
          void setColorClamped([Clamp] octet red, [Clamp] octet green, [Clamp] octet blue);
        };
    </pre>

    A call to <code>setColorClamped</code> with
    Number values that are out of range for an
    {{octet}} are clamped to the range [0, 255].

    <pre highlight="js">
        // Get an instance of GraphicsContext.
        var context = getGraphicsContext();

        // Calling the non-[Clamp] version uses ToUint8 to coerce the Numbers to octets.
        // This is equivalent to calling setColor(255, 255, 1).
        context.setColor(-1, 255, 257);

        // Call setColorClamped with some out of range values.
        // This is equivalent to calling setColorClamped(0, 255, 255).
        context.setColorClamped(-1, 255, 257);
    </pre>
</div>


<h4 id="Default" extended-attribute lt="Default">[Default]</h4>

If the [{{Default}}] [=extended attribute=] appears on a [=regular operation=],
then it indicates that steps described in the [=corresponding default operation=]
must be carried out when the operation is invoked.

The [{{Default}}] extended attribute must
[=takes no arguments|take no arguments=].

The [{{Default}}] extended attribute must not
be used on anything other than a [=regular operation=]
for which a [=corresponding default operation=] has been defined.

<div class="example" id="example-tojson-default">

    As an example, the [{{Default}}] extended attribute is suitable
    for use on <code>toJSON</code> [=regular operations=]:

    <pre highlight="webidl">
        [Exposed=Window]
        interface Animal {
          attribute DOMString name;
          attribute unsigned short age;
          [Default] object toJSON();
        };

        [Exposed=Window]
        interface Human : Animal {
          attribute Dog? pet;
          [Default] object toJSON();
        };

        [Exposed=Window]
        interface Dog : Animal {
          attribute DOMString? breed;
        };

    </pre>

    In the ECMAScript language binding, there would exist a <code>toJSON()</code> method on
    <code class="idl">Animal</code>, <code class="idl">Human</code>,
    and (via inheritance) <code class="idl">Dog</code> objects:

    <pre highlight="js">
        // Get an instance of Human.
        var alice = getHuman();

        // Evaluates to an object like this (notice how "pet" still holds
        // an instance of Dog at this point):
        //
        // {
        //   name: "Alice",
        //   age: 59,
        //   pet: Dog
        // }
        alice.toJSON();

        // Evaluates to an object like this (notice how "breed" is absent,
        // as the Dog interface doesn't declare a default toJSON operation):
        //
        // {
        //   name: "Tramp",
        //   age: 6
        // }
        alice.pet.toJSON();

        // Evaluates to a string like this:
        // '{"name":"Alice","age":59,"pet":{"name":"Tramp","age":6}}'
        JSON.stringify(alice);
    </pre>
</div>


<h4 id="EnforceRange" extended-attribute lt="EnforceRange">[EnforceRange]</h4>

If the [{{EnforceRange}}] [=extended attribute=] appears on one of the [=integer types=], it creates
a new IDL type such that that when an ECMAScript Number is converted to the IDL
type, out-of-range values will cause an exception to be thrown, rather than being converted to a
valid value using using the operators that use a modulo operation (<a abstract-op>ToInt32</a>, <a abstract-op>ToUint32</a>, etc.).
The Number will be rounded toward zero before being checked against its range.

The [{{EnforceRange}}]
extended attribute must
[=takes no arguments|take no arguments=].

A type annotated with the [{{EnforceRange}}] extended attribute must not appear in a
[=read only=] attribute. A type must not be [=extended attributes associated with|associated with=]
both the [{{Clamp}}] and [{{EnforceRange}}] extended attributes. A type that is not an
[=integer type=] must not be [=extended attributes associated with|associated with=] the
[{{EnforceRange}}] extended attribute.

See the rules for converting ECMAScript values to the various IDL integer
types in [[#es-type-mapping]]
for the specific requirements that the use of
[{{EnforceRange}}] entails.

<div class="example">

    In the following [=IDL fragment=],
    two [=operations=] are declared that
    take three {{octet}} arguments; one uses
    the [{{EnforceRange}}] [=extended attribute=]
    on all three arguments, while the other does not:

    <pre highlight="webidl">
        [Exposed=Window]
        interface GraphicsContext {
          void setColor(octet red, octet green, octet blue);
          void setColorEnforcedRange([EnforceRange] octet red, [EnforceRange] octet green, [EnforceRange] octet blue);
        };
    </pre>

    In an ECMAScript implementation of the IDL, a call to setColorEnforcedRange with
    Number values that are out of range for an
    {{octet}} will result in an exception being
    thrown.

    <pre highlight="js">
        // Get an instance of GraphicsContext.
        var context = getGraphicsContext();

        // Calling the non-[EnforceRange] version uses ToUint8 to coerce the Numbers to octets.
        // This is equivalent to calling setColor(255, 255, 1).
        context.setColor(-1, 255, 257);

        // When setColorEnforcedRange is called, Numbers are rounded towards zero.
        // This is equivalent to calling setColor(0, 255, 255).
        context.setColorEnforcedRange(-0.9, 255, 255.2);

        // The following will cause a TypeError to be thrown, since even after
        // rounding the first and third argument values are out of range.
        context.setColorEnforcedRange(-1, 255, 256);
    </pre>
</div>


<h4 id="Exposed" extended-attribute lt="Exposed">[Exposed]</h4>

When the [{{Exposed}}] [=extended attribute=] appears on
an [=interface=],
[=partial interface=],
[=interface mixin=],
[=partial interface mixin=],
[=callback interface=],
[=namespace=],
[=partial namespace=], or
an individual [=interface member=],
[=interface mixin member=], or
[=namespace member=],
it indicates that the construct is exposed
on that particular set of global interfaces.

The [{{Exposed}}] [=extended attribute=] must either
[=takes an identifier|take an identifier=] or
[=takes an identifier list|take an identifier list=].
Each of the identifiers mentioned must be a [=global name=] and be unique.
This list of identifiers is known as the construct's
<dfn>own exposure set</dfn>.

<div algorithm>

    To get the <dfn id="dfn-exposure-set" export>exposure set</dfn> of a construct |C|,
    run the following steps:

    1.  Assert: |C| is an [=interface=], [=callback interface=], [=namespace=],
        [=interface member=], [=interface mixin member=], or [=namespace member=].
    1.  Let |H| be |C|'s [=host interface=] if |C| is an [=interface mixin member=], or null otherwise.
    1.  If |C| is an [=interface member=], [=interface mixin member=], or [=namespace member=], then:
        1.  If the [{{Exposed}}] [=extended attribute=] is specified on |C|, then:
            1.  If |H| is set, return the [=set/intersection=] of |C|'s [=own exposure set=]
                and |H|'s [=exposure set=].
            1.  Otherwise, return |C|'s [=own exposure set=].
        1.  Otherwise, set |C| to be the
            [=interface=], [=partial interface=],
            [=interface mixin=], [=partial interface mixin=],
            [=namespace=], or [=partial namespace=]
            |C| is declared on.
    1.  If |C| is a [=partial interface=], [=partial interface mixin=], or [=partial namespace=], then:
        1.  If the [{{Exposed}}] [=extended attribute=] is specified on |C|, then:
            1.  If |H| is set, return the [=set/intersection=] of |C|'s [=own exposure set=]
                and |H|'s [=exposure set=].
            1.  Otherwise, return |C|'s [=own exposure set=].
        1.  Otherwise, set |C| to be the original [=interface=], [=interface mixin=], or [=namespace=]
            definition of |C|.
    1.  If |C| is an [=interface mixin=], then:
        1.  If the [{{Exposed}}] [=extended attribute=] is specified on |C|,
            then return the [=set/intersection=] of |C|'s [=own exposure set=]
            and |H|'s [=exposure set=].
        1.  Otherwise, set |C| to |H|.
    1.  Assert: |C| is an [=interface=], [=callback interface=] or [=namespace=].
    1.  Assert: The [{{Exposed}}] [=extended attribute=] is specified on |C|.
    1.  Return |C|'s [=own exposure set=].
</div>

If [{{Exposed}}] appears on an [=overloaded=] [=operation=],
then it must appear identically on all overloads.

The [{{Exposed}}] extended attribute must not be specified both on
an [=interface member=], [=interface mixin member=], or [=namespace member=], and on
the [=partial interface=], [=partial interface mixin=], or [=partial namespace=] definition
the [=member=] is declared on.

Note: This is because adding an [{{Exposed}}] [=extended attribute=] on a
[=partial interface=], [=partial interface mixin=], or [=partial namespace=]
is shorthand for annotating each of its [=members=].

If [{{Exposed}}] appears on a [=partial interface=] or [=partial namespace=],
then the partial's [=own exposure set=] must be a subset of
the [=exposure set=] of the partial's original [=interface=] or [=namespace=].

If [{{Exposed}}] appears on an [=interface member|interface=] or [=namespace member=],
then the [=member=]'s [=exposure set=] must be a subset
of the [=exposure set=] of the [=interface=] or [=namespace=] it is a member of.

If [{{Exposed}}] appears both on a [=partial interface mixin=]
and its original [=interface mixin=],
then the [=partial interface mixin=]'s [=own exposure set=]
must be a subset of the [=interface mixin=]'s [=own exposure set=].

If [{{Exposed}}] appears both on an [=interface mixin member=]
and the [=interface mixin=] it is a member of,
then the [=interface mixin members=]'s [=own exposure set=]
must be a subset of the [=interface mixin=]'s [=own exposure set=].

If an interface |X| [=interface/inherits=] from another interface |Y|
then the [=exposure set=] of |X| must be a subset of the [=exposure set=] of |Y|.

Note: As an [=interface mixin=] can be [=included=] by different [=interfaces=],
the [=exposure set=] of its [=interface mixin member|members=] is a function of
the [=interface=] that [=includes=] them.
If the [=interface mixin member=], [=partial interface mixin=], or [=interface mixin=]
is annotated with an [{{Exposed}}] [=extended attribute=],
then the [=interface mixin member=]'s [=exposure set=]
is the [=set/intersection=] of the relevant construct's [=own exposure set=]
with the the [=host interface=]'s [=exposure set=].
Otherwise, it is the [=host interface=]'s [=exposure set=].

<div algorithm>
    An [=interface=], [=callback interface=], [=namespace=], or [=member=] |construct| is
    <dfn id="dfn-exposed" export>exposed</dfn> in a given [=Realm=] |realm| if the following steps
    return true:

    1.  If |realm|.\[[GlobalObject]] does not implement an [=interface=]
        that is in |construct|'s [=exposure set=], then return false.
    1.  If |construct| is [=available in both secure and non-secure contexts=],
        then return true.
    1.  If the [=relevant settings object=] of |realm|.\[[GlobalObject]] is a [=secure context=],
        then return true.
    1.  Otherwise, return false.
</div>

Note: Since it is not possible for the [=relevant settings object=]
for an ECMAScript global object to change whether it is a
[=secure context=] or not over time, an implementation's
decision to create properties for an interface or interface member
can be made once, at the time the
[=initial objects=]
are created.

See
[[#es-interfaces]],
[[#es-constants]],
[[#es-attributes]],
[[#es-operations]], and
[[#es-iterators]]
for the specific requirements that the use of
[{{Exposed}}] entails.

<div class="example">

    [{{Exposed}}] is intended to be used to control whether [=interfaces=],
    [=callback interfaces=], [=namespaces=], or individual [=interface member|interface=],
    [=interface mixin member|mixin=] or [=namespace members=] are available for use in workers,
    {{Worklet}}, {{Window}}, or any combination of the above.

    The following IDL fragment shows how that might be achieved:

    <pre highlight="webidl">
        [Exposed=Window, Global=Window]
        interface Window {
          // ...
        };

        // By using the same identifier Worker for both SharedWorkerGlobalScope
        // and DedicatedWorkerGlobalScope, both can be addressed in an [Exposed]
        // extended attribute at once.
        [Exposed=Worker, Global=Worker]
        interface SharedWorkerGlobalScope : WorkerGlobalScope {
          // ...
        };

        [Exposed=Worker, Global=Worker]
        interface DedicatedWorkerGlobalScope : WorkerGlobalScope {
          // ...
        };

        // Dimensions is available for use in workers and on the main thread.
        [Exposed=(Window,Worker)]
        interface Dimensions {
          constructor(double width, double height);
          readonly attribute double width;
          readonly attribute double height;
        };

        // WorkerNavigator is only available in workers.  Evaluating WorkerNavigator
        // in the global scope of a worker would give you its interface object, while
        // doing so on the main thread will give you a ReferenceError.
        [Exposed=Worker]
        interface WorkerNavigator {
          // ...
        };

        // Node is only available on the main thread.  Evaluating Node
        // in the global scope of a worker would give you a ReferenceError.
        [Exposed=Window]
        interface Node {
          // ...
        };

        // MathUtils is available for use in workers and on the main thread.
        [Exposed=(Window,Worker)]
        namespace MathUtils {
          double someComplicatedFunction(double x, double y);
        };

        // WorkerUtils is only available in workers.  Evaluating WorkerUtils
        // in the global scope of a worker would give you its namespace object, while
        // doing so on the main thread will give you a ReferenceError.
        [Exposed=Worker]
        namespace WorkerUtils {
          void setPriority(double x);
        };

        // NodeUtils is only available in the main thread.  Evaluating NodeUtils
        // in the global scope of a worker would give you a ReferenceError.
        [Exposed=Window]
        namespace NodeUtils {
          DOMString getAllText(Node node);
        };
    </pre>
</div>


<h4 oldids="PrimaryGlobal" id="Global" extended-attribute lt="Global" dfn>[Global]</h4>

If the [{{Global}}] [=extended attribute=] appears on an [=interface=],
it indicates that objects implementing this interface can
be used as the global object in a [=Realm=],
and that the structure of the prototype chain and how
properties corresponding to [=interface members=]
will be reflected on the prototype objects will be different from other
interfaces. Specifically:

1.  Any [=named properties=]
    will be exposed on an object in the prototype chain – the
    [=named properties object=] –
    rather than on the object itself.
1.  [=Interface members=] from the
    [=interface=]
    will correspond to properties on the object itself rather than on
    [=interface prototype objects=].

<div class="note">

    Placing named properties on an object in the prototype chain
    is done so that variable declarations and bareword assignments
    will shadow the named property with a property on the global
    object itself.

    Placing properties corresponding to interface members on
    the object itself will mean that common feature detection
    methods like the following will work:

    <pre highlight="js">
        var indexedDB = window.indexedDB || window.webkitIndexedDB ||
                        window.mozIndexedDB || window.msIndexedDB;

        var requestAnimationFrame = window.requestAnimationFrame ||
                                    window.mozRequestAnimationFrame || ...;
    </pre>

    Because of the way variable declarations are handled in
    ECMAScript, the code above would result in the <code>window.indexedDB</code>
    and <code>window.requestAnimationFrame</code> evaluating
    to <emu-val>undefined</emu-val>, as the shadowing variable
    property would already have been created before the
    assignment is evaluated.

</div>

If the [{{Global}}] [=extended attributes=] is
used on an [=interface=], then:

*   The interface must not define a [=named property setter=].
*   The interface must not define [=indexed property getters=] or [=indexed property setter|setters=].
*   The interface must not define a [=constructor operation=].
*   The interface must not also be declared with the [{{OverrideBuiltins}}]
    extended attribute.
*   The interface must not [=interface/inherit=] from another interface with the
    [{{OverrideBuiltins}}] extended attribute.
*   Any other interface must not [=interface/inherit=] from it.

If [{{Global}}] is specified on
a [=partial interface=]
definition, then that partial interface definition must
be the part of the interface definition that defines
the [=named property getter=].

The [{{Global}}] [=extended attribute=] must not
be used on an [=interface=] that can have more
than one object implementing it in the same [=Realm=].

Note: This is because the [=named properties object=],
which exposes the named properties, is in the prototype chain, and it would not make
sense for more than one object’s named properties to be exposed on an object that
all of those objects inherit from.

If an interface is declared with the [{{Global}}] [=extended attribute=], then
there must not be more than one
[=member=] across
the interface
with the same [=identifier=].
There also must not be more than
one [=stringifier=]
or more than one [=iterable declaration=],
[=asynchronously iterable declaration=],
[=maplike declaration=] or
[=setlike declaration=]
across those interfaces.

Note: This is because all of the [=members=] of the interface
get flattened down on to the object that [=implements=] the interface.

The [{{Global}}] extended attribute
can also be used to give a name to one or more global interfaces,
which can then be referenced by the [{{Exposed}}]
extended attribute.

The [{{Global}}] extended attribute must either
[=takes an identifier|take an identifier=] or
[=takes an identifier list|take an identifier list=].

The identifier argument or identifier list argument the [{{Global}}] [=extended attribute=] is declared with
define the interface’s <dfn id="dfn-global-name" export>global names</dfn>.

Note: The identifier argument list exists so that more than one global interface can
be addressed with a single name in an [{{Exposed}}] [=extended attribute=].

See [[#named-properties-object]] for the specific requirements
that the use of [{{Global}}] entails for [=named properties=],
and [[#es-constants]], [[#es-attributes]] and [[#es-operations]]
for the requirements relating to the location of properties
corresponding to [=interface members=].

<div class="example">

    The <code class="idl">Window</code> interface exposes frames as properties on the <code class="idl">Window</code>
    object.  Since the <code class="idl">Window</code> object also serves as the
    ECMAScript global object, variable declarations or assignments to the named properties
    will result in them being replaced by the new value.  Variable declarations for
    attributes will not create a property that replaces the existing one.

    <pre highlight="webidl">
        [Exposed=Window, Global]
        interface Window {
          getter any (DOMString name);
          attribute DOMString name;
          // ...
        };
    </pre>

    The following HTML document illustrates how the named properties on the
    <code class="idl">Window</code> object can be shadowed, and how
    the property for an attribute will not be replaced when declaring
    a variable of the same name:

    <pre highlight="html">
        &lt;!DOCTYPE html&gt;
        &lt;title&gt;Variable declarations and assignments on Window&lt;/title&gt;
        &lt;iframe name=abc&gt;&lt;/iframe&gt;
        &lt;!-- Shadowing named properties --&gt;
        &lt;script&gt;
          window.abc;    // Evaluates to the iframe's Window object.
          abc = 1;       // Shadows the named property.
          window.abc;    // Evaluates to 1.
        &lt;/script&gt;

        &lt;!-- Preserving properties for IDL attributes --&gt;
        &lt;script&gt;
          Window.prototype.def = 2;         // Places a property on the prototype.
          window.hasOwnProperty("length");  // Evaluates to true.
          length;                           // Evaluates to 1.
          def;                              // Evaluates to 2.
        &lt;/script&gt;
        &lt;script&gt;
          var length;                       // Variable declaration leaves existing property.
          length;                           // Evaluates to 1.
          var def;                          // Variable declaration creates shadowing property.
          def;                              // Evaluates to undefined.
        &lt;/script&gt;
    </pre>
</div>


<h4 id="LegacyNamespace" extended-attribute lt="LegacyNamespace">[LegacyNamespace]</h4>

<p class="advisement">
    The [{{LegacyNamespace}}] [=extended attribute=] is an undesirable feature.
    It exists only so that legacy Web platform features can be specified.
    It should not be used in specifications
    unless required to specify the behavior of legacy APIs,
    or for consistency with these APIs.
    Instead, interface names
    can be formed with a naming convention of starting with a particular prefix for
    a set of interfaces, as part of the identifier, rather than using a namespace.
    Editors who wish to use this feature are strongly advised to discuss this
    by <a href="https://github.com/heycam/webidl/issues/new?title=Intent%20to%20use%20[LegacyNamespace]">filing an issue</a>
    before proceeding.
</p>

If the [{{LegacyNamespace}}] [=extended attribute=] appears on an [=interface=], it indicates that
the [=interface object=] for this interface will not be created as a property of the global
object, but rather as a property of the [=namespace=] identified by the argument to the extended
attribute.

The [{{LegacyNamespace}}] extended attribute [=takes an identifier|take an identifier=].
This identifier must be the identifier of a namespace.

The [{{LegacyNamespace}}] and [{{NoInterfaceObject}}]
extended attributes must not be specified on the same interface.

See [[#namespace-object]] for details on how an interface is exposed on a namespace.

<div class="example">
    The following [=IDL fragment=] defines a [=namespace=] and an [=interface=] which
    uses [{{LegacyNamespace}}] to be defined inside of it.

    <pre highlight="webidl">
        namespace Foo { };

        [LegacyNamespace=Foo]
        interface Bar {
          constructor();
        };
    </pre>

    In an ECMAScript implementation of the above namespace and interface, the
    constructor Bar can be accessed as follows:

    <pre highlight="js">
        var instance = new Foo.Bar();
    </pre>
</div>


<h4 id="LegacyUnenumerableNamedProperties" extended-attribute lt="LegacyUnenumerableNamedProperties">[LegacyUnenumerableNamedProperties]</h4>

<div class="advisement">

    The [{{LegacyUnenumerableNamedProperties}}] [=extended attribute=] is an undesirable feature.
    It exists only so that legacy Web platform features can be specified.
    It should not be used in specifications
    unless required to specify the behavior of legacy APIs,
    or for consistency with these APIs.
    Editors who wish to use this feature are strongly advised to discuss this
    by <a href="https://github.com/heycam/webidl/issues/new?title=Intent%20to%20use%20[LegacyUnenumerableNamedProperties]">filing an issue</a>
    before proceeding.

    <small class="non-normative">
        The [{{LegacyUnenumerableNamedProperties}}] [=extended attribute=] appears on
        the following [=interfaces=]:
        {{HTMLCollection}},
        {{NamedNodeMap}},
        {{HTMLAllCollection}},
        {{HTMLFormElement}},
        {{PluginArray}},
        {{MimeTypeArray}},
        {{Plugin}}, and
        {{Window}}. [[DOM]] [[HTML]]
    </small>

</div>

If the [{{LegacyUnenumerableNamedProperties}}]
[=extended attribute=]
appears on a [=interface=]
that [=support named properties|supports named properties=],
it indicates that all the interface's named properties are unenumerable.

The [{{LegacyUnenumerableNamedProperties}}]
extended attribute must
[=takes no arguments|take no arguments=]
and must not appear on an interface
that does not define a [=named property getter=].

If the [{{LegacyUnenumerableNamedProperties}}]
extended attribute is specified on an interface, then it applies to all its derived interfaces and
must not be specified on any of them.

See [[#legacy-platform-object-getownproperty]]
for the specific requirements that the use of
[{{LegacyUnenumerableNamedProperties}}]
entails.


<h4 id="LegacyWindowAlias" extended-attribute lt="LegacyWindowAlias">[LegacyWindowAlias]</h4>

<div class="advisement">

    The [{{LegacyWindowAlias}}] [=extended attribute=] is an undesirable feature.
    It exists only so that legacy Web platform features can be specified.
    It should not be used in specifications
    unless required to specify the behavior of legacy APIs,
    or for consistency with these APIs.
    Editors who wish to use this feature are strongly advised to discuss this
    by <a href="https://github.com/heycam/webidl/issues/new?title=Intent%20to%20use%20[LegacyWindowAlias]">filing an issue</a>
    before proceeding.

    <small class="non-normative">
        The [{{LegacyWindowAlias}}] [=extended attribute=] appears on the following [=interfaces=]:
        {{DOMPoint}},
        {{DOMRect}},
        {{DOMMatrix}}, and
        {{URL}}. [[GEOMETRY]] [[URL]]
    </small>

</div>

If the [{{LegacyWindowAlias}}] [=extended attribute=] appears on an [=interface=],
it indicates that the {{Window}} [=interface=] will have a property
for each [=identifier=] mentioned in the extended attribute,
whose value is the [=interface object=] for the interface.

The [{{LegacyWindowAlias}}] extended attribute must either
[=takes an identifier|take an identifier=] or
[=takes an identifier list|take an identifier list=].
The <emu-t class="regex"><a href="#prod-identifier">identifier</a></emu-t>s that occur after the
“<emu-t>=</emu-t>” are the [{{LegacyWindowAlias}}]'s <dfn lt="LegacyWindowAlias identifier">identifiers</dfn>.

Each of the [=LegacyWindowAlias identifier|identifiers=] of [{{LegacyWindowAlias}}]
must not be the same as one used by a [{{LegacyWindowAlias}}]
extended attribute on this interface or another interface,
must not be the same as the [=NamedConstructor identifier|identifier=] used by a [{{NamedConstructor}}]
extended attribute on this interface or another interface,
must not be the same as an [=identifier=] of an interface that has an [=interface object=],
and must not be one of the [=reserved identifiers=].

The [{{LegacyWindowAlias}}] and [{{NoInterfaceObject}}]
extended attributes must not be specified on the same interface.

The [{{LegacyWindowAlias}}] and [{{LegacyNamespace}}]
extended attributes must not be specified on the same interface.

The [{{LegacyWindowAlias}}] extended attribute must not be specified
on an interface that does not include the {{Window}} [=interface=]
in its [=exposure set=].

An interface must not have more than one [{{LegacyWindowAlias}}] extended attributes specified.

See [[#es-interfaces]] for details on how legacy window aliases
are to be implemented.

<div class="example">

    The following IDL defines an interface that uses the
    [{{LegacyWindowAlias}}] extended attribute.

    <pre highlight="webidl">
        [Exposed=Window,
         LegacyWindowAlias=WebKitCSSMatrix]
        interface DOMMatrix : DOMMatrixReadOnly {
          // ...
        };
    </pre>

    An ECMAScript implementation that supports this interface will
    expose two properties on the {{Window}} object with the same value
    and the same characteristics;
    one for exposing the [=interface object=] normally,
    and one for exposing it with a legacy name.

    <pre highlight="js">
        WebKitCSSMatrix === DOMMatrix;     // Evaluates to true.

        var m = new WebKitCSSMatrix();     // Creates a new object that
                                           // implements DOMMatrix.

        m.constructor === DOMMatrix;       // Evaluates to true.
        m.constructor === WebKitCSSMatrix; // Evaluates to true.
        {}.toString.call(m);               // Evaluates to '[object DOMMatrix]'.
    </pre>
</div>


<h4 id="LenientSetter" extended-attribute lt="LenientSetter">[LenientSetter]</h4>

<div class="advisement">

    Specifications should not use [{{LenientSetter}}]
    unless required for compatibility reasons.  Pages have been observed
    where authors have attempted to polyfill an IDL attribute by assigning
    to the property, but have accidentally done so even if the property
    exists.  In strict mode, this would cause an exception to be thrown,
    potentially breaking page.  Without [{{LenientSetter}}],
    this could prevent a browser from shipping the feature.
    Editors who wish to use this feature are strongly advised to discuss this
    by <a href="https://github.com/heycam/webidl/issues/new?title=Intent%20to%20use%20[LenientSetter]">filing an issue</a>
    before proceeding.

    <small class="non-normative">
        The [{{LenientSetter}}] [=extended attribute=] appears on
        the {{Document/fullscreenEnabled}} and {{Document/fullscreenEnabled}} [=attributes=]
        of the {{Document}} interface, and on
        the {{DocumentOrShadowRoot/fullscreenElement}} [=attribute=]
        of the {{DocumentOrShadowRoot}} [=interface mixin=]. [[FULLSCREEN]]
    </small>

</div>

If the [{{LenientSetter}}]
[=extended attribute=]
appears on a [=read only=]
[=regular attribute=],
it indicates that a no-op setter will be generated for the attribute’s
accessor property.  This results in erroneous assignments to the property
in strict mode to be ignored rather than causing an exception to be thrown.

The [{{LenientSetter}}] extended attribute
must [=takes no arguments|take no arguments=].
It must not be used on anything other than
a [=read only=] [=regular attribute=].

An attribute with the [{{LenientSetter}}]
extended attribute must not also be declared
with the [{{PutForwards}}]
or [{{Replaceable}}] extended attributes.

The [{{LenientSetter}}] extended attribute must not be used on an attribute declared on a
[=namespace=].

See the <a href="#es-attributes">Attributes</a> section for how
[{{LenientSetter}}] is to be implemented.

<div class="example">

    The following IDL fragment defines an interface that uses the
    [{{LenientSetter}}] extended
    attribute.

    <pre highlight="webidl">
        [Exposed=Window]
        interface Example {
          [LenientSetter] readonly attribute DOMString x;
          readonly attribute DOMString y;
        };
    </pre>

    An ECMAScript implementation that supports this interface will
    have a setter on the accessor property that correspond to x,
    which allows any assignment to be ignored in strict mode.

    <pre highlight="js">
        "use strict";

        var example = getExample();  // Get an instance of Example.

        // Fine; while we are in strict mode, there is a setter that is a no-op.
        example.x = 1;

        // Throws a TypeError, since we are in strict mode and there is no setter.
        example.y = 1;
    </pre>
</div>


<h4 id="LenientThis" extended-attribute lt="LenientThis">[LenientThis]</h4>

<div class="advisement">

    Specifications should not use [{{LenientThis}}]
    unless required for compatibility reasons.
    Editors who wish to use this feature are strongly advised to discuss this
    by <a href="https://github.com/heycam/webidl/issues/new?title=Intent%20to%20use%20[LenientThis]">filing an issue</a>
    before proceeding.

    <small class="non-normative">
        The [{{LenientThis}}] [=extended attribute=] appears on
        the {{Document/onreadystatechange}},
        {{Document/onmouseenter}}, and
        {{Document/onmouseleave}} [=attributes=]
        of the {{Document}} interface. [[HTML]]
    </small>

</div>

If the [{{LenientThis}}]
[=extended attribute=]
appears on a [=regular attribute=],
it indicates that invocations of the attribute’s getter or setter
with a <emu-val>this</emu-val> value that is not an
object that [=implements=] the [=interface=]
on which the attribute appears will be ignored.

The [{{LenientThis}}] extended attribute
must
[=takes no arguments|take no arguments=].
It must not be used on a
[=static attribute=].

The [{{LenientThis}}] extended attribute must not be used on an attribute declared on a
[=namespace=].

See the <a href="#es-attributes">Attributes</a> section for how
[{{LenientThis}}]
is to be implemented.

<div class="example">

    The following IDL fragment defines an interface that uses the
    [{{LenientThis}}] extended
    attribute.

    <pre highlight="webidl">
        [Exposed=Window]
        interface Example {
          [LenientThis] attribute DOMString x;
          attribute DOMString y;
        };
    </pre>

    An ECMAScript implementation that supports this interface will
    allow the getter and setter of the accessor property that corresponds
    to x to be invoked with something other than an <code class="idl">Example</code>
    object.

    <pre highlight="js">
        var example = getExample();  // Get an instance of Example.
        var obj = { };

        // Fine.
        example.x;

        // Ignored, since the this value is not an Example object and [LenientThis] is used.
        Object.getOwnPropertyDescriptor(Example.prototype, "x").get.call(obj);

        // Also ignored, since Example.prototype is not an Example object and [LenientThis] is used.
        Example.prototype.x;

        // Throws a TypeError, since Example.prototype is not an Example object.
        Example.prototype.y;
    </pre>
</div>


<h4 id="NamedConstructor" extended-attribute lt="NamedConstructor">[NamedConstructor]</h4>

<div class="advisement">

    [{{NamedConstructor}}] [=extended attribute=] is an undesirable feature.
    It exists only so that legacy Web platform features can be specified.
    It should not be used in specifications
    unless required to specify the behavior of legacy APIs,
    or for consistency with these APIs.
    Editors who wish to use this feature are strongly advised to discuss this
    by <a href="https://github.com/heycam/webidl/issues/new?title=Intent%20to%20use%20[NamedConstructor]">filing an issue</a>
    before proceeding.

    <small class="non-normative">
        The [{{NamedConstructor}}] [=extended attribute=] appears on the following [=interfaces=]:
        {{HTMLAudioElement}},
        {{HTMLOptionElement}}, and
        {{HTMLImageElement}}. [[HTML]]
    </small>

</div>

If the [{{NamedConstructor}}]
[=extended attribute=]
appears on an [=interface=],
it indicates that the ECMAScript global object will have a property with the
specified name whose value is a [=constructor=] that can
create objects that implement the interface.
Multiple [{{NamedConstructor}}] extended
attributes may appear on a given interface.

The [{{NamedConstructor}}] extended attribute must either
[=takes an identifier|take an identifier=] or
[=takes a named argument list|take a named argument list=].
The <emu-t class="regex"><a href="#prod-identifier">identifier</a></emu-t> that occurs directly after the
“<emu-t>=</emu-t>” is the [{{NamedConstructor}}]'s <dfn lt="NamedConstructor identifier">identifier</dfn>.
The first form, <code>[NamedConstructor=<emu-t class="regex"><a href="#prod-identifier">identifier</a></emu-t>]</code>,
has the same meaning as using an empty argument list,
<code>[NamedConstructor=<emu-t class="regex"><a href="#prod-identifier">identifier</a></emu-t>()]</code>.
For each [{{NamedConstructor}}] extended attribute on the interface,
there will be a way to construct an object that
[=implements=] the interface by passing the specified arguments to the [=constructor=]
that is the value of the aforementioned property.

The [=NamedConstructor identifier|identifier=] used for the named constructor must not
be the same as that used by a [{{NamedConstructor}}]
extended attribute on another interface, must not
be the same as an [=LegacyWindowAlias identifier|identifier=] used by a [{{LegacyWindowAlias}}]
extended attribute on this interface or another interface,
must not be the same as an [=identifier=] of an interface
that has an [=interface object=],
and must not be one of the
[=reserved identifiers=].

The [{{NamedConstructor}}] and [{{Global}}] [=extended attributes=] must not be specified on the
same [=interface=].

See [[#named-constructors]] for details on how named constructors
are to be implemented.

<div class="example">

    The following IDL defines an interface that uses the
    [{{NamedConstructor}}] extended
    attribute.

    <pre highlight="webidl">
        [Exposed=Window,
         NamedConstructor=Audio,
         NamedConstructor=Audio(DOMString src)]
        interface HTMLAudioElement : HTMLMediaElement {
          // ...
        };
    </pre>

    An ECMAScript implementation that supports this interface will
    allow the construction of <code class="idl">HTMLAudioElement</code>
    objects using the <code class="idl">Audio</code> [=constructor=].

    <pre highlight="js">
        typeof Audio;                   // Evaluates to 'function'.

        var a1 = new Audio();           // Creates a new object that implements
                                        // HTMLAudioElement, using the zero-argument
                                        // constructor.

        var a2 = new Audio('a.flac');   // Creates an HTMLAudioElement using the
                                        // one-argument constructor.
    </pre>
</div>


<h4 id="NewObject" extended-attribute lt="NewObject">[NewObject]</h4>

If the [{{NewObject}}]
[=extended attribute=]
appears on a [=regular operation|regular=]
or [=static operations|static=]
[=operation=],
then it indicates that when calling the operation,
a reference to a newly created object
must always be returned.

The [{{NewObject}}]
extended attribute must
[=takes no arguments|take no arguments=].

The [{{NewObject}}]
extended attribute must not
be used on anything other than a [=regular operation|regular=]
or [=static operations|static=]
[=operation=]
whose [=return type=]
is an [=interface type=] or
a [=promise type=].

<div class="example">

    As an example, this extended attribute is suitable for use on
    the {{Document/createElement()}} operation on the {{Document}} interface,
    since a new object should always be returned when
    it is called. [[DOM]]

    <pre highlight="webidl">
        [Exposed=Window]
        interface Document : Node {
          [NewObject] Element createElement(DOMString localName);
          // ...
        };
    </pre>
</div>


<h4 id="NoInterfaceObject" extended-attribute lt="NoInterfaceObject">[NoInterfaceObject]</h4>

<div class="advisement">

    The [{{NoInterfaceObject}}] [=extended attribute=] is an undesirable feature.
    It exists only so that legacy Web platform features can be specified.
    It should not be used in specifications
    unless required to specify the behavior of legacy APIs,
    or for consistency with these APIs.
    Editors who wish to use this feature are strongly advised to discuss this
    by <a href="https://github.com/heycam/webidl/issues/new?title=Intent%20to%20use%20[NoInterfaceObject]">filing an issue</a>
    before proceeding.

    <small class="non-normative">
        The [{{NoInterfaceObject}}] [=extended attribute=] appears on the following [=interfaces=]:

        {{Geolocation}},
        {{Coordinates}},
        {{Position}},
        {{PositionError}},
        {{DeviceAcceleration}},
        {{DeviceRotationRate}},
        {{ConstrainablePattern}},
        {{WEBGL_compressed_texture_astc}},
        {{WEBGL_compressed_texture_s3tc_srgb}},
        {{WEBGL_draw_buffers}},
        {{WEBGL_lose_context}},
        {{ANGLE_instanced_arrays}},
        {{EXT_blend_minmax}},
        {{EXT_color_buffer_float}},
        {{EXT_disjoint_timer_query}},
        {{OES_standard_derivatives}}, and
        {{OES_vertex_array_object}}.
        [[GEOLOCATION-API]]
        [[ORIENTATION-EVENT]]
        [[MEDIACAPTURE-STREAMS]]
        (various [[WEBGL]] extension specifications)
    </small>

    Note: Previously, the [{{NoInterfaceObject}}] [=extended attribute=] could also be used
    to annotate [=interfaces=], which other [=interfaces=] could then implement
    (using the defunct "implements statement") as if they were mixins.
    There is now dedicated syntax to cater for this use case
    in the form of [=interface mixins=] and [=includes statements=].
    Using the [{{NoInterfaceObject}}] [=extended attribute=]
    for this purpose is no longer supported.
    Specifications which still do are strongly encouraged
    to migrate to [=interface mixins=] as soon as possible.
</div>

If the [{{NoInterfaceObject}}] [=extended attribute=] appears on an [=interface=],
it indicates that an [=interface object=]
will not exist for the interface in the ECMAScript binding.

The [{{NoInterfaceObject}}] extended attribute
must [=takes no arguments|take no arguments=].

The [{{NoInterfaceObject}}] extended attribute
must not be specified on an interface that has any
[=constructors=] or [=static operations=] defined on it.

Note: Combining the [{{NoInterfaceObject}}] and [{{NamedConstructor}}] extended attribute is not
forbidden, however.

An interface that does not have the [{{NoInterfaceObject}}] extended
attribute specified must not inherit
from an interface that has the [{{NoInterfaceObject}}] extended
attribute specified.

See [[#es-interfaces]]
for the specific requirements that the use of
[{{NoInterfaceObject}}] entails.

<div class="example">

    The following [=IDL fragment=] defines two interfaces, one whose interface object
    is exposed on the ECMAScript global object, and one whose isn’t:

    <pre highlight="webidl">
        [Exposed=Window]
        interface Storage {
          void addEntry(unsigned long key, any value);
        };

        [Exposed=Window,
         NoInterfaceObject]
        interface Query {
          any lookupEntry(unsigned long key);
        };
    </pre>

    An ECMAScript implementation of the above IDL would allow
    manipulation of <code class="idl">Storage</code>’s
    prototype, but not <code class="idl">Query</code>’s.

    <pre highlight="js">
        typeof Storage;                        // evaluates to "object"

        // Add some tracing alert() call to Storage.addEntry.
        var fn = Storage.prototype.addEntry;
        Storage.prototype.addEntry = function(key, value) {
          alert('Calling addEntry()');
          return fn.call(this, key, value);
        };

        typeof Query;                          // evaluates to "undefined"
        var fn = Query.prototype.lookupEntry;  // exception, Query isn’t defined
    </pre>
</div>


<h4 id="OverrideBuiltins" extended-attribute lt="OverrideBuiltins">[OverrideBuiltins]</h4>

<div class="advisement">

    The [{{OverrideBuiltins}}] [=extended attribute=] is an undesirable feature.
    It exists only so that legacy Web platform features can be specified.
    It should not be used in specifications
    unless required to specify the behavior of legacy APIs,
    or for consistency with these APIs.
    Editors who wish to use this feature are strongly advised to discuss this
    by <a href="https://github.com/heycam/webidl/issues/new?title=Intent%20to%20use%20[OverrideBuiltins]">filing an issue</a>
    before proceeding.

    <small class="non-normative">
        The [{{OverrideBuiltins}}] [=extended attribute=] appears on the
        {{DOMStringMap}},
        {{Document}}, and
        {{HTMLFormElement}} [=interfaces=]. [[HTML]]
    </small>

</div>

If the [{{OverrideBuiltins}}]
[=extended attribute=]
appears on an [=interface=],
it indicates that for a [=legacy platform object=] implementing the interface,
properties corresponding to all of
the object’s [=supported property names=]
will appear to be on the object,
regardless of what other properties exist on the object or its
prototype chain.  This means that named properties will always shadow
any properties that would otherwise appear on the object.
This is in contrast to the usual behavior, which is for named properties
to be exposed only if there is no property with the
same name on the object itself or somewhere on its prototype chain.

The [{{OverrideBuiltins}}]
extended attribute must
[=takes no arguments|take no arguments=]
and must not appear on an interface
that does not define a [=named property getter=]
or that also is declared with the [{{Global}}] [=extended attribute=].
If the extended attribute is specified on
a [=partial interface=]
definition, then that partial interface definition must
be the part of the interface definition that defines
the [=named property getter=].

If the [{{OverrideBuiltins}}] extended attribute is specified on a
[=partial interface=] definition, it is considered to appear on the
[=interface=] itself.

See [[#es-legacy-platform-objects]]
and [[#legacy-platform-object-defineownproperty]]
for the specific requirements that the use of
[{{OverrideBuiltins}}] entails.

<div class="example">

    The following [=IDL fragment=]
    defines two [=interfaces=],
    one that has a [=named property getter=]
    and one that does not.

    <pre highlight="webidl">
        [Exposed=Window]
        interface StringMap {
          readonly attribute unsigned long length;
          getter DOMString lookup(DOMString key);
        };

        [Exposed=Window,
         OverrideBuiltins]
        interface StringMap2 {
          readonly attribute unsigned long length;
          getter DOMString lookup(DOMString key);
        };
    </pre>

    In an ECMAScript implementation of these two interfaces,
    getting certain properties on objects implementing
    the interfaces will result in different values:

    <pre highlight="js">
        // Obtain an instance of StringMap.  Assume that it has "abc", "length" and
        // "toString" as supported property names.
        var map1 = getStringMap();

        // This invokes the named property getter.
        map1.abc;

        // This fetches the "length" property on the object that corresponds to the
        // length attribute.
        map1.length;

        // This fetches the "toString" property from the object's prototype chain.
        map1.toString;

        // Obtain an instance of StringMap2.  Assume that it also has "abc", "length"
        // and "toString" as supported property names.
        var map2 = getStringMap2();

        // This invokes the named property getter.
        map2.abc;

        // This also invokes the named property getter, despite the fact that the "length"
        // property on the object corresponds to the length attribute.
        map2.length;

        // This too invokes the named property getter, despite the fact that "toString" is
        // a property in map2's prototype chain.
        map2.toString;
    </pre>
</div>


<h4 id="PutForwards" extended-attribute lt="PutForwards">[PutForwards]</h4>

If the [{{PutForwards}}]
[=extended attribute=]
appears on a [=read only=]
[=regular attribute=] declaration whose type is
an [=interface type=],
it indicates that assigning to the attribute will have specific behavior.
Namely, the assignment is “forwarded” to the attribute (specified by
the extended attribute argument) on the object that is currently
referenced by the attribute being assigned to.

The [{{PutForwards}}] extended
attribute must [=takes an identifier|take an identifier=].
Assuming that:

*   |A| is the [=attribute=]
    on which the [{{PutForwards}}]
    extended attribute appears,
*   |I| is the [=interface=]
    on which |A| is declared,
*   |J| is the [=interface type=]
    that |A| is declared to be of, and
*   |N| is the [=identifier=]
    argument of the extended attribute,

then there must be another
[=attribute=] |B|
declared on |J| whose [=identifier=]
is |N|.  Assignment of a value to the attribute |A|
on an object implementing |I| will result in that value
being assigned to attribute |B| of the object that |A|
references, instead.

Note that [{{PutForwards}}]-annotated
[=attributes=] can be
chained.  That is, an attribute with the [{{PutForwards}}]
[=extended attribute=]
can refer to an attribute that itself has that extended attribute.
There must not exist a cycle in a
chain of forwarded assignments.  A cycle exists if, when following
the chain of forwarded assignments, a particular attribute on
an [=interface=] is
encountered more than once.

An attribute with the [{{PutForwards}}]
extended attribute must not also be declared
with the [{{LenientSetter}}] or
[{{Replaceable}}] extended attributes.

The [{{PutForwards}}]
extended attribute must not be used
on an [=attribute=] that
is not [=read only=].

The [{{PutForwards}}] extended attribute
must not be used on a
[=static attribute=].

The [{{PutForwards}}] extended attribute
must not be used on an attribute declared on
a [=namespace=].

See the <a href="#es-attributes">Attributes</a> section for how
[{{PutForwards}}]
is to be implemented.

<div class="example">

    The following [=IDL fragment=] defines interfaces for names and people.
    The [{{PutForwards}}] extended
    attribute is used on the <code class="idl">name</code> attribute
    of the <code class="idl">Person</code> interface to indicate
    that assignments to that attribute result in assignments to the
    <code class="idl">full</code> attribute of the
    <code class="idl">Person</code> object:

    <pre highlight="webidl">
        [Exposed=Window]
        interface Name {
          attribute DOMString full;
          attribute DOMString family;
          attribute DOMString given;
        };

        [Exposed=Window]
        interface Person {
          [PutForwards=full] readonly attribute Name name;
          attribute unsigned short age;
        };
    </pre>

    In the ECMAScript binding, this would allow assignments to the
    <code class="idl">name</code> property:

    <pre highlight="js">
        var p = getPerson();           // Obtain an instance of Person.

        p.name = 'John Citizen';       // This statement...
        p.name.full = 'John Citizen';  // ...has the same behavior as this one.
    </pre>
</div>


<h4 id="Replaceable" extended-attribute lt="Replaceable">[Replaceable]</h4>

If the [{{Replaceable}}]
[=extended attribute=]
appears on a [=read only=]
[=regular attribute=],
it indicates that setting the corresponding property on the
[=platform object=] will result in
an own property with the same name being created on the object
which has the value being assigned.  This property will shadow
the accessor property corresponding to the attribute, which
exists on the [=interface prototype object=].

The [{{Replaceable}}]
extended attribute must
[=takes no arguments|take no arguments=].

An attribute with the [{{Replaceable}}]
extended attribute must not also be declared
with the [{{LenientSetter}}] or
[{{PutForwards}}] extended attributes.

The [{{Replaceable}}]
extended attribute must not be used
on an [=attribute=] that
is not [=read only=].

The [{{Replaceable}}] extended attribute
must not be used on a
[=static attribute=].

The [{{Replaceable}}] extended attribute
must not be used on an attribute declared on
a [=namespace=].

See [[#es-attributes]]
for the specific requirements that the use of
[{{Replaceable}}] entails.

<div class="example">

    The following [=IDL fragment=]
    defines an [=interface=]
    with an [=operation=]
    that increments a counter, and an [=attribute=]
    that exposes the counter’s value, which is initially 0:

    <pre highlight="webidl">
        [Exposed=Window]
        interface Counter {
          [Replaceable] readonly attribute unsigned long value;
          void increment();
        };
    </pre>

    Assigning to the <code class="idl">value</code> property
    on a [=platform object=] implementing <code class="idl">Counter</code>
    will shadow the property that corresponds to the
    [=attribute=]:

    <pre highlight="js">
        var counter = getCounter();                              // Obtain an instance of Counter.
        counter.value;                                           // Evaluates to 0.

        counter.hasOwnProperty("value");                         // Evaluates to false.
        Object.getPrototypeOf(counter).hasOwnProperty("value");  // Evaluates to true.

        counter.increment();
        counter.increment();
        counter.value;                                           // Evaluates to 2.

        counter.value = 'a';                                     // Shadows the property with one that is unrelated
                                                                 // to Counter::value.

        counter.hasOwnProperty("value");                         // Evaluates to true.

        counter.increment();
        counter.value;                                           // Evaluates to 'a'.

        delete counter.value;                                    // Reveals the original property.
        counter.value;                                           // Evaluates to 3.
    </pre>
</div>


<h4 id="SameObject" extended-attribute lt="SameObject">[SameObject]</h4>

If the [{{SameObject}}]
[=extended attribute=]
appears on a [=read only=]
[=attribute=], then it
indicates that when getting the value of the attribute on a given
object, the same value must always
be returned.

The [{{SameObject}}]
extended attribute must
[=takes no arguments|take no arguments=].

The [{{SameObject}}]
extended attribute must not
be used on anything other than a [=read only=]
[=attribute=]
whose type is an [=interface type=]
or {{object}}.

<div class="example">

    As an example, this extended attribute is suitable for use on
    the {{Document/implementation}} attribute on the {{Document}} interface
    since the same object is always returned for a given
    {{Document}} object. [[DOM]]

    <pre highlight="webidl">
        [Exposed=Window]
        interface Document : Node {
          [SameObject] readonly attribute DOMImplementation implementation;
          // ...
        };
    </pre>
</div>


<h4 id="SecureContext" extended-attribute lt="SecureContext">[SecureContext]</h4>

If the [{{SecureContext}}] [=extended attribute=] appears on an
[=interface=],
[=partial interface=],
[=interface mixin=],
[=partial interface mixin=],
[=callback interface=],
[=namespace=],
[=partial namespace=],
[=interface member=],
[=interface mixin member=], or
[=namespace member=],
it indicates that the construct is [=exposed=]
only within a [=secure context=].
The [{{SecureContext}}] extended attribute must not be used
on any other construct.

The [{{SecureContext}}] extended attribute must [=takes no arguments|take no arguments=].

A construct is <dfn export>available in both secure and non-secure contexts</dfn> if it is not
[=available only in secure contexts=] (i.e., if no [{{SecureContext}}] extended attribute applies
to it).

<div algorithm>

    To check if a construct |C| is
    <dfn id="dfn-available-only-in-secure-contexts" export>available only in secure contexts</dfn>,
    run the following steps:

    1.  Assert: |C| is an [=interface=], [=callback interface=], [=namespace=],
        [=interface member=], [=interface mixin member=], or [=namespace member=].
    1.  Let |H| be |C|'s [=host interface=] if |C| is an [=interface mixin member=], or null otherwise.
    1.  If |C| is an [=interface member=], [=interface mixin member=], or [=namespace member=], then:
        1.  If the [{{SecureContext}}] [=extended attribute=] is specified on |C|,
            then return true.
        1.  Otherwise, set |C| to be the
            [=interface=], [=partial interface=],
            [=interface mixin=], [=partial interface mixin=],
            [=namespace=], or [=partial namespace=]
            |C| is declared on.
    1.  If |C| is a [=partial interface=], [=partial interface mixin=], or [=partial namespace=], then:
        1.  If the [{{SecureContext}}] [=extended attribute=] is specified on |C|,
            then return true.
        1.  Otherwise, set |C| to be the original [=interface=], [=interface mixin=], or [=namespace=]
            definition of |C|.
    1.  If |C| is an [=interface mixin=], then:
        1.  If the [{{SecureContext}}] [=extended attribute=] is specified on |C|,
            then return true.
        1.  Otherwise, set |C| to |H|.
    1.  Assert: |C| is an [=interface=], [=callback interface=] or [=namespace=].
    1.  If the [{{SecureContext}}] [=extended attribute=] is specified on |C|,
        then return true.
    1.  Otherwise, return false.
</div>

Note: Whether a construct is [=available only in secure contexts=]
influences whether it is [=exposed=] in a given [=Realm=].

If [{{SecureContext}}] appears on an [=overloaded=] [=operation=],
then it must appear on all overloads.

The [{{SecureContext}}] [=extended attribute=] must not be specified both on

* an [=interface member=] and its [=interface=] or [=partial interface=];
* an [=interface mixin member=] and its [=interface mixin=] or [=partial interface mixin=];
* a [=namespace member=] and its [=namespace=] or [=partial namespace=].

Note: This is because adding the [{{SecureContext}}] [=extended attribute=] on a [=member=] when
its containing definition is also annotated with the [{{SecureContext}}] [=extended attribute=]
does not further restrict the exposure of the [=member=].

An [=interface=] without the [{{SecureContext}}] [=extended attribute=]
must not [=interface/inherit=] from another interface
that does specify [{{SecureContext}}].

<div class="example">

    The following [=IDL fragment=] defines an interface
    with one [=operation=] that is executable from all
    contexts, and two which are executable only from secure contexts.

    <pre highlight="webidl">
        [Exposed=Window]
        interface PowerfulFeature {
          // This call will succeed in all contexts.
          Promise &lt;Result&gt; calculateNotSoSecretResult();

          // This operation will not be exposed to a non-secure context. In such a context,
          // there will be no "calculateSecretResult" property on PowerfulFeature.prototype.
          [SecureContext] Promise&lt;Result&gt; calculateSecretResult();

          // The same applies here: the attribute will not be exposed to a non-secure context,
          // and in a non-secure context there will be no "secretBoolean" property on
          // PowerfulFeature.prototype.
          [SecureContext] readonly attribute boolean secretBoolean;
        };

        // HeartbeatSensor will not be exposed in a non-secure context, nor will its members.
        // In such a context, there will be no "HeartbeatSensor" property on Window.
        [SecureContext]
        interface HeartbeatSensor {
          Promise&lt;float&gt; getHeartbeatsPerMinute();
        };

        // The interface mixin members defined below will never be exposed in a non-secure context,
        // regardless of whether the interface that includes them is.
        // In a non-secure context, there will be no "snap" property on
        // PowerfulFeature.prototype.
        [SecureContext]
        interface mixin Snapshotable {
          Promise&lt;boolean&gt; snap();
        };
        PowerfulFeature includes Snapshotable;

        // On the other hand, the following interface mixin members will be exposed
        // to a non-secure context when included by a host interface
        // that doesn't have the [SecureContext] extended attribute.
        // In a non-secure context, there will be a "log" property on
        // PowerfulFeatures.prototype.
        interface mixin Loggable {
          Promise&lt;boolean&gt; log();
        };
        PowerfulFeatures includes Loggable;
    </pre>
</div>


<h4 id="TreatNonObjectAsNull" extended-attribute lt="TreatNonObjectAsNull">[TreatNonObjectAsNull]</h4>

<div class="advisement">

    The [{{TreatNonObjectAsNull}}] [=extended attribute=] is an undesirable feature.
    It exists only so that legacy Web platform features can be specified.
    It should not be used in specifications
    unless required to specify the behavior of legacy APIs,
    or for consistency with these APIs.
    Editors who wish to use this feature are strongly advised to discuss this
    by <a href="https://github.com/heycam/webidl/issues/new?title=Intent%20to%20use%20[TreatNonObjectAsNull]">filing an issue</a>
    before proceeding.

    <small class="non-normative">
        The [{{TreatNonObjectAsNull}}] [=extended attribute=] appears on
        the [=callback functions=] {{EventHandlerNonNull}},
        {{OnBeforeUnloadEventHandlerNonNull}}, and
        {{OnErrorEventHandlerNonNull}}
        used as the type of [=event handler IDL attributes=]
        such as <code>onclick</code> and <code>onerror</code>. [[HTML]]
    </small>

</div>

If the [{{TreatNonObjectAsNull}}]
[=extended attribute=]
appears on a [=callback function=],
then it indicates that any value assigned to an [=attribute=]
whose type is a [=nullable type|nullable=]
[=callback function=]
that is not an object will be converted to
the <emu-val>null</emu-val> value.

See [[#es-nullable-type]]
for the specific requirements that the use of
[{{TreatNonObjectAsNull}}] entails.

<div class="example">

    The following [=IDL fragment=] defines an interface that has one
    attribute whose type is a [{{TreatNonObjectAsNull}}]-annotated
    [=callback function=] and another whose type is a
    [=callback function=] without the [=extended attribute=]:

    <pre highlight="webidl">
        callback OccurrenceHandler = void (DOMString details);

        [TreatNonObjectAsNull]
        callback ErrorHandler = void (DOMString details);

        [Exposed=Window]
        interface Manager {
          attribute OccurrenceHandler? handler1;
          attribute ErrorHandler? handler2;
        };
    </pre>

    In an ECMAScript implementation, assigning a value that is not
    an object (such as a Number value)
    to handler1 will have different behavior from that when assigning
    to handler2:

    <pre highlight="js">
        var manager = getManager();  // Get an instance of Manager.

        manager.handler1 = function() { };
        manager.handler1;            // Evaluates to the function.

        try {
          manager.handler1 = 123;    // Throws a TypeError.
        } catch (e) {
        }

        manager.handler2 = function() { };
        manager.handler2;            // Evaluates to the function.

        manager.handler2 = 123;
        manager.handler2;            // Evaluates to null.
    </pre>
</div>


<h4 id="TreatNullAs" extended-attribute lt="TreatNullAs">[TreatNullAs]</h4>

<p class="advisement">
    The [{{TreatNullAs}}] [=extended attribute=] is an undesirable feature.
    It exists only so that legacy Web platform features can be specified.
    It should not be used in specifications
    unless required to specify the behavior of legacy APIs,
    or for consistency with these APIs.
    Editors who wish to use this feature are strongly advised to discuss this
    by <a href="https://github.com/heycam/webidl/issues/new?title=Intent%20to%20use%20[TreatNullAs]">filing an issue</a>
    before proceeding.
</div>

If the [{{TreatNullAs}}] [=extended attribute=] appears on the {{DOMString}} type, it creates a new
IDL type such that that when an ECMAScript <emu-val>null</emu-val> is converted to the IDL type, it
will be handled differently from its default handling. Instead of being stringified to
"<code>null</code>", which is the default, it will be converted to the empty string.

The [{{TreatNullAs}}] extended attribute must [=takes an identifier|take the identifier=]
<code>EmptyString</code>.

The [{{TreatNullAs}}] extended attribute must not be
[=extended attribute associated with|associated with=] a type that is not {{DOMString}}.

Note: This means that even <code class="idl">DOMString?</code> must not use [{{TreatNullAs}}], since
<emu-val>null</emu-val> is a valid value of that type.

See [[#es-DOMString]] for the specific requirements that the use of [{{TreatNullAs}}] entails.

<div class="example">
    The following [=IDL fragment=] defines an interface that has one attribute whose type has the
    extended attribute, and one operation whose argument's type has the extended attribute:

    <pre highlight="webidl">
        [Exposed=Window]
        interface Dog {
          attribute DOMString name;
          attribute [TreatNullAs=EmptyString] DOMString owner;

          boolean isMemberOfBreed([TreatNullAs=EmptyString] DOMString breedName);
        };
    </pre>

    An ECMAScript implementation implementing the <code class="idl">Dog</code>
    interface would convert a <emu-val>null</emu-val> value
    assigned to the <code>owner</code> property or passed as the
    argument to the <code>isMemberOfBreed</code> function
    to the empty string rather than "<code>null</code>":

    <pre highlight="js">
        var d = getDog();         // Assume d is a platform object implementing the Dog
                                  // interface.

        d.name = null;            // This assigns the string "null" to the .name
                                  // property.

        d.owner = null;           // This assigns the string "" to the .owner property.

        d.isMemberOfBreed(null);  // This passes the string "" to the isMemberOfBreed
                                  // function.
    </pre>
</div>


<h4 id="Unforgeable" extended-attribute lt="Unforgeable">[Unforgeable]</h4>

If the [{{Unforgeable}}] [=extended attribute=] appears on
[=regular attributes=] or non-[=static operations|static=] [=operations=],
it indicates that the attribute or operation
will be reflected as an ECMAScript property
in a way that means its behavior cannot be modified
and that performing a property lookup on the object
will always result in the attribute’s property value being returned.
In particular, the property will be non-configurable
and will exist as an own property on the object itself
rather than on its prototype.

An attribute or operation is said to be
<dfn id="dfn-unforgeable-on-an-interface" export>unforgeable</dfn> on a given interface |A|
if the attribute or operation is declared on |A|,
and is annotated with the [{{Unforgeable}}] [=extended attribute=].

The [{{Unforgeable}}] extended attribute must [=takes no arguments|take no arguments=].

The [{{Unforgeable}}] [=extended attribute=] must not appear
on anything other than a [=regular attribute=]
or a non-[=static operations|static=] [=operation=].
If it does appear on an [=operation=],
then it must appear on all operations
with the same [=identifier=] on that interface.

The [{{Unforgeable}}] extended attribute must not be used
on an attribute declared on a [=namespace=].

If an attribute or operation |X| is [=unforgeable=] on an interface |A|,
and |A| is one of the [=inherited interfaces=] of another interface |B|,
then |B| must not have a [=regular attribute=]
or non-[=static operations|static=] [=operation=]
with the same [=identifier=] as |X|.

<div class="note">

    For example, the following is disallowed:

    <pre highlight="webidl">
        [Exposed=Window]
        interface A1 {
          [Unforgeable] readonly attribute DOMString x;
        };
        [Exposed=Window]
        interface B1 : A1 {
          void x();  // Invalid; would be shadowed by A1's x.
        };

        [Exposed=Window]
        interface B2 : A1 { };
        B2 includes M1;
        interface mixin M1 {
          void x();  // Invalid; B2's copy of x would be shadowed by A1's x.
        };
    </pre>
</div>

See [[#es-attributes]],
[[#es-operations]],
[[#es-platform-objects]],
[[#es-legacy-platform-objects]] and
[[#legacy-platform-object-defineownproperty]]
for the specific requirements that the use of
[{{Unforgeable}}] entails.

<div class="example">

    The following [=IDL fragment=] defines
    an interface that has two [=attributes=],
    one of which is designated as [{{Unforgeable}}]:

    <pre highlight="webidl">
        [Exposed=Window]
        interface System {
          [Unforgeable] readonly attribute DOMString username;
          readonly attribute long long loginTime;
        };
    </pre>

    In an ECMAScript implementation of the interface, the username attribute will be exposed as a non-configurable property on the
    object itself:

    <pre highlight="js">
        var system = getSystem();                      // Get an instance of System.

        system.hasOwnProperty("username");             // Evaluates to true.
        system.hasOwnProperty("loginTime");            // Evaluates to false.
        System.prototype.hasOwnProperty("username");   // Evaluates to false.
        System.prototype.hasOwnProperty("loginTime");  // Evaluates to true.

        try {
          // This call would fail, since the property is non-configurable.
          Object.defineProperty(system, "username", { value: "administrator" });
        } catch (e) { }

        // This defineProperty call would succeed, because System.prototype.loginTime
        // is configurable.
        var forgedLoginTime = 5;
        Object.defineProperty(System.prototype, "loginTime", { value: forgedLoginTime });

        system.loginTime;  // So this now evaluates to forgedLoginTime.
    </pre>
</div>


<h4 id="Unscopable" extended-attribute lt="Unscopable">[Unscopable]</h4>

If the [{{Unscopable}}]
[=extended attribute=]
appears on a [=regular attribute=]
or [=regular operation=], it
indicates that an object that [=implements=] an interface with the given
interface member will not include its property name in any object
environment record with it as its base object.  The result of this is
that bare identifiers matching the property name will not resolve to
the property in a <code>with</code> statement.  This is achieved by
including the property name on the
[=interface prototype object=]’s
{{@@unscopables}} property’s value.

The [{{Unscopable}}]
extended attribute must
[=takes no arguments|take no arguments=].

The [{{Unscopable}}]
extended attribute must not appear on
anything other than a [=regular attribute=]
or [=regular operation=].

The [{{Unscopable}}] extended attribute must not be used on an attribute declared on a
[=namespace=].

See [[#interface-prototype-object]]
for the specific requirements that the use of
[{{Unscopable}}] entails.

<div class="note">

    For example, with the following IDL:

    <pre highlight="webidl">
        [Exposed=Window]
        interface Thing {
          void f();
          [Unscopable] g();
        };
    </pre>

    the <code class="idl">f</code> property can be referenced with a bare identifier
    in a <code>with</code> statement but the <code class="idl">g</code> property cannot:

    <pre highlight="js">
        var thing = getThing();  // An instance of Thing
        with (thing) {
          f;                     // Evaluates to a Function object.
          g;                     // Throws a ReferenceError.
        }
    </pre>
</div>


<h3 id="es-security">Security</h3>

Certain algorithms in the sections below are defined to
<dfn id="dfn-perform-a-security-check" export>perform a security check</dfn> on a given
object.  This check is used to determine whether a given
[=operation=] invocation or
[=attribute=] access should be
allowed.  The security check takes the following three inputs:

1.  the [=platform object=] on
    which the operation invocation or attribute access is being done,
1.  the [=identifier=]
    of the operation or attribute, and
1.  the type of the [=function object=] –
    "<code>method</code>" (when it corresponds to an IDL operation), or
    "<code>getter</code>" or "<code>setter</code>" (when it corresponds to the
    getter or setter function of an IDL attribute).

Note: The HTML Standard defines how a security check is performed. [[!HTML]]


<h3 id="es-overloads">Overload resolution algorithm</h3>

<div algorithm>

    In order to define how function invocations are resolved, the
    <dfn id="dfn-overload-resolution-algorithm" export>overload resolution algorithm</dfn>
    is defined.  Its input is an [=effective overload set=],
    |S|, and a list of ECMAScript values, |args|.
    Its output is a pair consisting of the [=operation=] or
    [=extended attribute=] of one of |S|’s entries
    and a list of IDL values or the special value “missing”.  The algorithm behaves as follows:

    1.  Let |maxarg| be the length of the longest type list of the entries in |S|.
    1.  Let |n| be the [=list/size=] of |args|.
    1.  Initialize |argcount| to be min(|maxarg|, |n|).
    1.  Remove from |S| all entries whose type list is not of length |argcount|.
    1.  If |S| is empty, then [=ECMAScript/throw=] a {{ECMAScript/TypeError}}.
    1.  Initialize |d| to −1.
    1.  Initialize |method| to <emu-val>undefined</emu-val>.
    1.  If there is more than one entry in |S|, then set
        |d| to be the [=distinguishing argument index=]
        for the entries of |S|.
    1.  Initialize |values| to be an empty list, where each entry will be either an IDL value or the special value “missing”.
    1.  Initialize |i| to 0.
    1.  While |i| &lt; |d|:
        1.  Let |V| be |args|[|i|].
        1.  Let |type| be the type at index |i| in the type list of any entry in |S|.

            Note: All entries in |S| at this point have the same type and [=optionality value=] at index |i|.

        1.  Let |optionality| be the value at index |i| in the list of [=optionality values=] of any entry in |S|.
        1.  If |optionality| is “optional” and |V| is <emu-val>undefined</emu-val>, then:
            1.  If the argument at index |i| is declared with a [=optional argument/default value=],
                then append to |values| that default value.
            1.  Otherwise, append to |values| the special value “missing”.
        1.  Otherwise, append to |values| the result of [=converted to an IDL value|converting=]
            |V| to IDL type |type|.
        1.  Set |i| to |i| + 1.
    1.  If |i| = |d|, then:
        1.  Let |V| be |args|[|i|].

            Note: This is the argument that will be used to resolve which overload is selected.

        1.  If |V| is <emu-val>undefined</emu-val>, and there is an entry in |S|
            whose list of [=optionality values=] has “optional” at index |i|,
            then remove from |S| all other entries.

        1.  Otherwise: if |V| is <emu-val>null</emu-val> or <emu-val>undefined</emu-val>,
            and there is an entry in |S| that has one of the following types at position |i| of its type list,
            *   a [=nullable type=]
            *   a [=dictionary type=]
            *   an [=annotated type=] whose [=annotated types/inner type=] is one of the above types
            *   a [=union type=] or [=annotated type|annotated=] union type that [=includes a nullable type=] or that
                has a [=dictionary type=] in its [=flattened member types|flattened members=]

            then remove from |S| all other entries.

        1.  Otherwise: if |V| [=is a platform object=], and
            there is an entry in |S| that has one of the following types at position |i| of its type list,
            *   an [=interface type=] that |V| [=implements=]
            *   {{object}}
            *   a [=nullable type|nullable=] version of any of the above types
            *   an [=annotated type=] whose [=annotated types/inner type=] is one of the above types
            *   a [=union type=], [=nullable type|nullable=] union type, or [=annotated type|annotated=] union type
                that has one of the above types in its [=flattened member types=]

            then remove from |S| all other entries.

        1.  Otherwise: if <a abstract-op>Type</a>(|V|) is Object, |V| has an \[[ArrayBufferData]] [=internal slot=], and
            there is an entry in |S| that has one of the following types at position |i| of its type list,
            *   {{ArrayBuffer}}
            *   {{object}}
            *   a [=nullable type|nullable=] version of either of the above types
            *   an [=annotated type=] whose [=annotated types/inner type=] is one of the above types
            *   a [=union type=], [=nullable type|nullable=] union type, or [=annotated type|annotated=] union type
                that has one of the above types in its [=flattened member types=]

            then remove from |S| all other entries.

        1.  Otherwise: if <a abstract-op>Type</a>(|V|) is Object, |V| has a \[[DataView]] [=internal slot=], and
            there is an entry in |S| that has one of the following types at position |i| of its type list,
            *   {{DataView}}
            *   {{object}}
            *   a [=nullable type|nullable=] version of either of the above types
            *   an [=annotated type=] whose [=annotated types/inner type=] is one of the above types
            *   a [=union type=], [=nullable type|nullable=] union type, or [=annotated type|annotated=] union type
                that has one of the above types in its [=flattened member types=]

            then remove from |S| all other entries.

        1.  Otherwise: if <a abstract-op>Type</a>(|V|) is Object, |V| has a \[[TypedArrayName]] [=internal slot=], and
            there is an entry in |S| that has one of the following types at position |i| of its type list,
            *   a [=typed array type=] whose name
                is equal to the value of |V|’s \[[TypedArrayName]] [=internal slot=]
            *   {{object}}
            *   a [=nullable type|nullable=] version of either of the above types
            *   an [=annotated type=] whose [=annotated types/inner type=] is one of the above types
            *   a [=union type=], [=nullable type|nullable=] union type, or [=annotated type|annotated=] union type
                that has one of the above types in its [=flattened member types=]

            then remove from |S| all other entries.

        1.  Otherwise: if <a abstract-op>IsCallable</a>(|V|) is true,
            and there is an entry in |S| that has one of the following types at position |i| of its type list,
            *   a [=callback function=] type
            *   {{object}}
            *   a [=nullable type|nullable=] version of any of the above types
            *   an [=annotated type=] whose [=annotated types/inner type=] is one of the above types
            *   a [=union type=], [=nullable type|nullable=] union type, or [=annotated type|annotated=] union type
                that has one of the above types in its [=flattened member types=]

            then remove from |S| all other entries.

        1.  Otherwise: if <a abstract-op>Type</a>(|V|) is Object and
            there is an entry in |S| that has one of the
            following types at position |i| of its type list,
            *   a [=sequence type=]
            *   a [=frozen array type=]
            *   a [=nullable type|nullable=] version of any of the above types
            *   an [=annotated type=] whose [=annotated types/inner type=] is one of the above types
            *   a [=union type=], [=nullable type|nullable=] union type, or [=annotated type|annotated=] union type
                that has one of the above types in its [=flattened member types=]

            and after performing the following steps,

            1.  Let |method| be [=?=] <a abstract-op>GetMethod</a>(|V|, {{@@iterator}}).

            |method| is not <emu-val>undefined</emu-val>, then remove from |S| all
            other entries.

        1.  Otherwise: if <a abstract-op>Type</a>(|V|) is Object and
            there is an entry in |S| that has one of the following types at position |i| of its type list,
            *   a [=callback interface type=]
            *   a [=dictionary type=]
            *   a [=record type=]
            *   {{object}}
            *   a [=nullable type|nullable=] version of any of the above types
            *   an [=annotated type=] whose [=annotated types/inner type=] is one of the above types
            *   a [=union type=], [=nullable type|nullable=] union type, or [=annotated type|annotated=] union type
                that has one of the above types in its [=flattened member types=]

            then remove from |S| all other entries.

        1.  Otherwise: if <a abstract-op>Type</a>(|V|) is Boolean
            and there is an entry in |S| that has one of the following types at position |i| of its type list,
            *   {{boolean}}
            *   a [=nullable type|nullable=] {{boolean}}
            *   an [=annotated type=] whose [=annotated types/inner type=] is one of the above types
            *   a [=union type=], [=nullable type|nullable=] union type, or [=annotated type|annotated=] union type
                that has one of the above types in its [=flattened member types=]

            then remove from |S| all other entries.

        1.  Otherwise: if <a abstract-op>Type</a>(|V|) is Number
            and there is an entry in |S| that has one of the following types at position |i| of its type list,
            *   a [=numeric type=]
            *   a [=nullable type|nullable=] [=numeric type=]
            *   an [=annotated type=] whose [=annotated types/inner type=] is one of the above types
            *   a [=union type=], [=nullable type|nullable=] union type, or [=annotated type|annotated=] union type
                that has one of the above types in its [=flattened member types=]

            then remove from |S| all other entries.

        1.  Otherwise: if there is an entry in |S| that has one of the following types at position |i| of its type list,
            *   a [=string type=]
            *   a [=nullable type|nullable=] version of any of the above types
            *   an [=annotated type=] whose [=annotated types/inner type=] is one of the above types
            *   a [=union type=], [=nullable type|nullable=] union type, or [=annotated type|annotated=] union type
                that has one of the above types in its [=flattened member types=]

            then remove from |S| all other entries.

        1.  Otherwise: if there is an entry in |S| that has one of the following types at position |i| of its type list,
            *   a [=numeric type=]
            *   a [=nullable type|nullable=] [=numeric type=]
            *   an [=annotated type=] whose [=annotated types/inner type=] is one of the above types
            *   a [=union type=], [=nullable type|nullable=] union type, or [=annotated type|annotated=] union type
                that has one of the above types in its [=flattened member types=]

            then remove from |S| all other entries.

        1.  Otherwise: if there is an entry in |S| that has one of the following types at position |i| of its type list,
            *   {{boolean}}
            *   a [=nullable type|nullable=] {{boolean}}
            *   an [=annotated type=] whose [=annotated types/inner type=] is one of the above types
            *   a [=union type=], [=nullable type|nullable=] union type, or [=annotated type|annotated=] union type
                that has one of the above types in its [=flattened member types=]

            then remove from |S| all other entries.

        1.  Otherwise: if there is an entry in |S| that has {{any}} at position |i|
            of its type list, then remove from |S| all other entries.
        1.  Otherwise: [=ECMAScript/throw=] a {{ECMAScript/TypeError}}.
    1.  Let |callable| be the [=operation=] or [=extended attribute=]
        of the single entry in |S|.
    1.  If |i| = |d| and |method| is not <emu-val>undefined</emu-val>, then
        1.  Let |V| be |args|[|i|].
        1.  Let |T| be the type at index |i| in the
            type list of the remaining entry in |S|.
        1.  If |T| is a [=sequence type=], then
            append to |values| the result of
            [=creating a sequence from an iterable|creating a sequence=]
            of type |T| from |V| and |method|.
        1.  Otherwise, |T| is a [=frozen array type=].
            Append to |values| the result of
            [=Creating a frozen array from an iterable|creating a frozen array of type T from V and method=].
        1.  Set |i| to |i| + 1.
    1.  While |i| &lt; |argcount|:
        1.  Let |V| be |args|[|i|].
        1.  Let |type| be the type at index |i| in the type list of the remaining entry in |S|.
        1.  Let |optionality| be the value at index |i| in the list of [=optionality values=] of the remaining entry in |S|.
        1.  If |optionality| is “optional” and |V| is <emu-val>undefined</emu-val>, then:
            1.  If the argument at index |i| is declared with a [=optional argument/default value=],
                then append to |values| that default value.
            1.  Otherwise, append to |values| the special value “missing”.
        1.  Otherwise, append to |values| the result of
            [=converted to an IDL value|converting=] |V| to IDL type |type|.
        1.  Set |i| to |i| + 1.
    1.  While |i| is less than the number of arguments |callable| is declared to take:
        1.  If |callable|’s argument at index |i| is declared with a [=optional argument/default value=],
            then append to |values| that default value.
        1.  Otherwise, if |callable|’s argument at index |i| is not variadic, then append to |values| the special value “missing”.
        1.  Set |i| to |i| + 1.
    1.  Return the pair &lt;|callable|, |values|&gt;.
</div>

<div class="note">

    The overload resolution algorithm performs both the identification
    of which overloaded operation, constructor, etc. is being called,
    and the conversion of the ECMAScript argument values to their
    corresponding IDL values.  Informally, it operates as follows.

    First, the selection of valid overloads is done by considering
    the number of ECMAScript arguments that were passed in to the function:

    *   If there are more arguments passed in than the longest
        overload argument list, then they are ignored.
    *   After ignoring these trailing arguments, only overloads
        that can take this exact number of arguments are considered.
        If there are none, then a {{ECMAScript/TypeError}} is thrown.

    Once we have a set of possible overloads with the right number
    of arguments, the ECMAScript values are converted from left to right.
    The nature of the restrictions on overloading means that if we
    have multiple possible overloads at this point, then there will
    be one position in the argument list that will be used to
    distinguish which overload we will finally select; this is
    the [=distinguishing argument index=].

    We first convert the arguments to the left of the distinguishing
    argument.  (There is a requirement that an argument to the left of
    the distinguishing argument index has the same type as in the other
    overloads, at the same index.) Then we inspect the type of the
    ECMAScript value that is passed in at the distinguishing argument
    index to determine which IDL type it may correspond to.
    This allows us to select the final overload that will
    be invoked.  If the value passed in is <emu-val>undefined</emu-val>
    and there is an overload with an optional argument at this position, then
    we will choose that overload.  If there is no valid overload for the type of
    value passed in here, then we throw a {{ECMAScript/TypeError}}.
    Generally, the inspection of the value at the distinguishing argument index does not have any
    side effects, and the only side effects in the overload resolution algorithm are the result of
    converting the ECMAScript values to IDL values.
    (An exception exists when one of the overloads has a [=sequence type=] or [=frozen array type=]
    at the distinguishing argument index.
    In this case, we attempt to get the {{@@iterator}} property to determine the appropriate
    overload, and perform the conversion of the distinguishing argument separately before continuing
    with the next step.)

    At this point, we have determined which overload to use.  We now
    convert the remaining arguments, from the distinguishing argument onwards,
    again ignoring any additional arguments that were ignored due to being passed
    after the last possible argument.

    When converting an optional argument’s ECMAScript value to its equivalent IDL value,
    <emu-val>undefined</emu-val> will be converted into
    the [=optional argument/default value|optional argument’s default value=],
    if it has one, or a special value “missing” otherwise.

    Optional arguments corresponding to a final, variadic argument do not treat
    <emu-val>undefined</emu-val> as a special “missing” value, however.
    The <emu-val>undefined</emu-val> value is converted to the type
    of variadic argument as would be done for a non-optional argument.

</div>


<h3 id="es-interfaces">Interfaces</h3>

For every [=interface=] that is [=exposed=] in
a given [=Realm=] and that is not declared with
the [{{NoInterfaceObject}}] or [{{LegacyNamespace}}] [=extended attributes=],
a corresponding property exists on the [=Realm=]'s [=Realm/global object=].
The name of the property is the [=identifier=] of the interface,
and its value is an object called the <dfn id="dfn-interface-object" export>interface object</dfn>.
The characteristics of an interface object are described in [[#interface-object]].

If the [{{LegacyWindowAlias}}] extended attribute was specified on an [=exposed=] interface,
then for each [=LegacyWindowAlias identifier|identifier=] in [{{LegacyWindowAlias}}]'s [=LegacyWindowAlias identifier|identifiers=]
there exists a corresponding property on the {{Window}} global object.
The name of the property is the given [=LegacyWindowAlias identifier|identifier=],
and its value is a reference to the [=interface object=] for the [=interface=].

In addition, for every [{{NamedConstructor}}] extended attribute on an [=exposed=] interface,
a corresponding property exists on the ECMAScript global object.
The name of the property is the [{{NamedConstructor}}]'s [=NamedConstructor identifier|identifier=],
and its value is an object called a <dfn id="dfn-named-constructor" export>named constructor</dfn>,
which allows construction of objects that implement the interface.
The characteristics of a named constructor are described in [[#named-constructors]].


<h4 id="interface-object" oldids="es-interface-call,es-constructible-interfaces">Interface object</h4>

The [=interface object=] for a given [=interface=] is a [=built-in function object=].
It has properties that correspond to the [=constants=] and [=static operations=]
defined on that interface,
as described in sections [[#es-constants]] and [[#es-operations]].

If the [=interface=] is declared with a [=constructor operation=],
then the [=interface object=] can be called as a [=constructor=]
to create an object that [=implements=] that interface.
Calling that interface as a function will throw an exception.

[=Interface objects=] whose [=interfaces=] are not declared
with a [=constructor operation=] will throw when called,
both as a function and as a [=constructor=].

An [=interface object=] for an [=interface=]
has an associated object called the [=interface prototype object=].
This object has properties that correspond to
the [=regular attributes=] and [=regular operations=] defined on the interface,
and is described in more detail in [[#interface-prototype-object]].

Note: Since an [=interface object=] is a [=function object=]
the <code>typeof</code> operator will return "function" when applied to an interface object.

An interface may have <dfn export>overridden constructor steps</dfn>, which can
change the behavior of the [=interface object=] when called or constructed. By
default interfaces do not have such steps.

<p class="advisement">
    In general, constructors are described by defining a [=constructor operation=] and its behavior.
    The [=overridden constructor steps=] are used only for more complicated situations.
    Editors who wish to use this feature are strongly advised to discuss this by
    <a href="https://github.com/heycam/webidl/issues/new?title=Intent%20to%20use%20constructor%20steps">filing an issue</a> before proceeding.
</p>

<div algorithm>

    The [=interface object=] for a given [=interface=] |I|
    with [=identifier=] |id| and in [=Realm=] |realm|
    is <dfn lt="create an interface object">created</dfn> as follows:

    1.  Let |steps| be |I|'s [=overridden constructor steps=] if they exist, or
        the following steps otherwise:
        1.  If |I| was not declared with a [=constructor operation=],
            then [=ECMAScript/throw=] a {{ECMAScript/TypeError}}.
        1.  If {{NewTarget}} is <emu-val>undefined</emu-val>, then
            [=ECMAScript/throw=] a {{ECMAScript/TypeError}}.
        1.  Let |args| be the passed arguments.
        1.  Let |n| be the [=list/size=] of |args|.
        1.  Let |id| be the identifier of interface |I|.
        1.  [=Compute the effective overload set=] for constructors with [=identifier=] |id| on
            [=interface=] |I| and with argument count |n|, and let |S| be the result.
        1.  Let &lt;|constructor|, |values|&gt; be the result
            of passing |S| and |args|.
            to the [=overload resolution algorithm=].
        1.  Let |object| be the result of [=internally create a new object implementing the
            interface|internally creating a new object implementing=] |I|, with |realm| and
            {{NewTarget}}.
        1.  Perform the actions listed in the description of |constructor|
            with |values| as the argument values
            and |object| as <b>[=this=]</b>.
        1.  Let |O| be |object|, [=converted to an ECMAScript value=].
        1.  Assert: |O| is an object that [=implements=] |I|.
        1.  Assert: |O|.\[[Realm]] is |realm|.
        1.  Return |O|.
    1.  Let |constructorProto| be |realm|.\[[Intrinsics]].[[{{%FunctionPrototype%}}]].
    1.  If |I| inherits from some other interface |P|,
        then set |constructorProto| to the [=interface object=] of |P| in |realm|.
    1.  Let |F| be [=!=] <a abstract-op>CreateBuiltinFunction</a>(|steps|, « \[[Unforgeables]] »,
        |realm|, |constructorProto|).
    1.  Let |unforgeables| be [$ObjectCreate$](<emu-val>null</emu-val>).
    1.  [=Define the unforgeable regular operations=] of |I| on |unforgeables|, given |realm|.
    1.  [=Define the unforgeable regular attributes=] of |I| on |unforgeables|, given |realm|.
    1.  Set |F|.\[[Unforgeables]] to |unforgeables|.

        Note: this object is never exposed to user code. It exists only to ensure all instances
        of an interface with an unforgeable member use the same JavaScript function objects for
        [=attribute getters=], [=attribute setters=] and [=creating an operation
        function|operation functions=].
    1.  Perform [=!=] <a abstract-op>SetFunctionName</a>(|F|, |id|).
    1.  Let |length| be 0.
    1.  If |I| was declared with a [=constructor operation=], then
        1.  [=Compute the effective overload set=] for constructors with [=identifier=] |id| on
            [=interface=] |I| and with argument count 0, and let |S| be the result.
        1.  Set |length| to the length of the
            shortest argument list of the entries in |S|.
    1.  Perform [=!=] <a abstract-op>SetFunctionLength</a>(|F|, |length|).
    1.  Let |proto| be the result of [=create an interface prototype object|creating an interface
        prototype object=] of [=interface=] |I| in |realm|.
    1.  Perform [=!=] <a abstract-op>DefinePropertyOrThrow</a>(|F|, "<code>prototype</code>",
        PropertyDescriptor{\[[Value]]: |proto|, \[[Writable]]: <emu-val>false</emu-val>, \[[Enumerable]]: <emu-val>false</emu-val>, \[[Configurable]]: <emu-val>false</emu-val>}).
    1.  [=Define the constants=] of [=interface=] |I| on |F| given |realm|.
    1.  [=Define the static attributes=] of [=interface=] |I| on |F| given |realm|.
    1.  [=Define the static operations=] of [=interface=] |I| on |F| given |realm|.
    1.  Return |F|.

</div>


<h4 id="named-constructors">Named constructors</h4>

A [=named constructor=] that exists due to one or more
[{{NamedConstructor}}] [=extended attributes=]
with a given [=NamedConstructor identifier|identifier=] is a [=built-in function object=].
It allows constructing objects that
implement the interface on which the
[{{NamedConstructor}}] extended attributes appear.

<div algorithm>

    The [=named constructor=] with [=NamedConstructor identifier|identifier=] |id|
    for a given [=interface=] |I| in Realm |realm|
    is <dfn lt="create a named constructor">created</dfn> as follows:

    1.  Let |steps| be the following steps:
        1.  If {{NewTarget}} is <emu-val>undefined</emu-val>, then
            [=ECMAScript/throw=] a {{ECMAScript/TypeError}}.
        1.  Let |args| be the passed arguments.
        1.  Let |n| be the [=list/size=] of |args|.
        1.  [=Compute the effective overload set=] for named constructors with [=identifier=] |id|
            on [=interface=] |I| and with argument count |n|, and let |S| be the result.
        1.  Let &lt;|constructor|, |values|&gt; be the result of passing |S| and
            |args| to the [=overload resolution algorithm=].
        1.  Let |object| be the result of [=internally create a new object implementing the
            interface|internally creating a new object implementing=] |I|, with |realm| and
            {{NewTarget}}.
        1.  Perform the actions listed in the description of |constructor|
            with |values| as the argument values
            and |object| as <b>[=this=]</b>.
        1.  Let |O| be |object|, [=converted to an ECMAScript value=].
        1.  Assert: |O| is an object that [=implements=] |I|.
        1.  Assert: |O|.\[[Realm]] is |realm|.
        1.  Return |O|.
    1.  Let |F| be [=!=] <a abstract-op>CreateBuiltinFunction</a>(|steps|, « », |realm|).
    1.  Perform [=!=] <a abstract-op>SetFunctionName</a>(|F|, |id|).
    1.  [=Compute the effective overload set=] for named constructors with [=identifier=] |id|
        on [=interface=] |I| and with argument count 0, and let |S| be the result.
    1.  Let |length| be the length of the shortest argument list of the entries in |S|.
    1.  Perform [=!=] <a abstract-op>SetFunctionLength</a>(|F|, |length|).
    1.  Let |proto| be the [=interface prototype object=] of [=interface=] |I| in |realm|.
    1.  Perform [=!=] <a abstract-op>DefinePropertyOrThrow</a>(|F|, "<code>prototype</code>",
        PropertyDescriptor{\[[Value]]: |proto|, \[[Writable]]: <emu-val>false</emu-val>, \[[Enumerable]]: <emu-val>false</emu-val>, \[[Configurable]]: <emu-val>false</emu-val>}).
    1.  Return |F|.
</div>


<h4 id="interface-prototype-object">Interface prototype object</h4>

There will exist an <dfn id="dfn-interface-prototype-object" export>interface prototype object</dfn>
for every [=interface=] defined,
regardless of whether the interface was declared
with the [{{NoInterfaceObject}}] [=extended attribute=].

<div algorithm>

    The [=interface prototype object=] for a given [=interface=] |interface| and [=Realm=] |realm|
    is <dfn lt="create an interface prototype object">created</dfn> as follows:

    1.  Let |proto| be null.
    1.  If |interface| is declared with the [{{Global}}] [=extended attribute=],
        and |interface| [=support named properties|supports named properties=],
        then set |proto| to the result of [=create a named properties object|creating a named
        properties object=] for |interface| and |realm|.
    1.  Otherwise, if |interface| is declared to inherit from another interface,
        then set |proto| to the [=interface prototype object=] in |realm|
        of that [=inherited interface=].
    1.  Otherwise, if |interface| is the {{DOMException}} [=interface=],
        then set |proto| to |realm|.\[[Intrinsics]].[[{{%ErrorPrototype%}}]].
    1.  Otherwise, set |proto| to |realm|.\[[Intrinsics]].[[{{%ObjectPrototype%}}]].
    1.  Assert: <a abstract-op>Type</a>(|proto|) is Object.
    1.  Let |interfaceProtoObj| be [=!=] <a abstract-op>ObjectCreate</a>(|proto|).
    1.  If |interface| has any [=member=] declared with the [{{Unscopable}}] [=extended attribute=],
        then:

        Issue: Should an {{@@unscopables}} property also be defined if |interface| is
        declared with the [{{Global}}] [=extended attribute=]?
        This is discussed in <a href="https://github.com/heycam/webidl/issues/544">issue #544</a>.
        1.  Let |unscopableObject| be the result of performing [=!=]
            <a abstract-op>ObjectCreate</a>(<emu-val>null</emu-val>).
        1.  [=list/For each=] [=exposed=] [=member=] |member| of |interface|
            that is declared with the [{{Unscopable}}] [=extended attribute=]:
            1.  Let |id| be |member|'s [=identifier=].
            1.  Perform [=!=] <a abstract-op>CreateDataProperty</a>(|unscopableObject|, |id|,
                <emu-val>true</emu-val>).
        1.  Let |desc| be the PropertyDescriptor{\[[Value]]: |unscopableObject|,
            \[[Writable]]: <emu-val>false</emu-val>, \[[Enumerable]]: <emu-val>false</emu-val>,
            \[[Configurable]]: <emu-val>true</emu-val>}.
        1.  Perform [=!=] <a abstract-op>DefinePropertyOrThrow</a>(|interfaceProtoObj|, {{@@unscopables}}, |desc|).
    1.  If |interface| is declared with the [{{Global}}] [=extended attribute=], or
        |interface| is in the set of [=inherited interfaces=] of an interface
        that is declared with the [{{Global}}] [=extended attribute=], then:
        1.  Set the internal methods of |interfaceProtoObj|
            which are specific to [=immutable prototype exotic objects=]
            to the definitions specified in
            [=ECMA-262 Immutable prototype exotic objects=].
    1.  If |interface| is not declared with the [{{Global}}] [=extended attribute=], then:
        1.  [=Define the regular attributes=] of |interface| on |interfaceProtoObj| given |realm|.
        1.  [=Define the regular operations=] of |interface| on |interfaceProtoObj| given |realm|.
    1.  [=Define the constants=] of |interface| on |interfaceProtoObj| given |realm|.
    1.  If the [{{NoInterfaceObject}}] [=extended attribute=] was not specified on |interface|, then:
        1.  Let |constructor| be the [=interface object=] of |interface| in |realm|.
        1.  Let |desc| be the PropertyDescriptor{\[[Writable]]: <emu-val>true</emu-val>,
            \[[Enumerable]]: <emu-val>false</emu-val>, \[[Configurable]]: <emu-val>true</emu-val>,
            \[[Value]]: |constructor|}.
        1.  Perform [=!=] <a abstract-op>DefinePropertyOrThrow</a>(|interfaceProtoObj|, "<code>constructor</code>", |desc|).
    1.  Return |interfaceProtoObj|.
</div>

Additionally, [=interface prototype objects=] get properties declaratively from:

* [[#es-stringifier]],
* [[#es-iterators]],
* [[#es-iterable]],
* [[#es-maplike]], and
* [[#es-setlike]].

Issue: Define those properties imperatively instead.

<div class="note">

    The [=interface prototype object=]
    of an [=interface=] that is defined with
    the [{{NoInterfaceObject}}]
    [=extended attribute=]
    will be accessible.
    For example, with the following IDL:

    <pre highlight="webidl">
        [Exposed=Window,
         NoInterfaceObject]
        interface Foo {
        };

        partial interface Window {
          attribute Foo foo;
        };
    </pre>

    it is not possible to access the interface prototype object through
    the [=interface object=]
    (since it does not exist as <code>window.Foo</code>).  However, an instance
    of <code class="idl">Foo</code> can expose the interface prototype
    object by calling its \[[GetPrototypeOf]]
    [=internal method=] – <code>Object.getPrototypeOf(window.foo)</code> in
    this example.

</div>

The [=class string=] of an [=interface prototype object=] is the concatenation of
the [=interface=]’s [=qualified name=] and the string "<code>Prototype</code>".


<h4 id="named-properties-object">Named properties object</h4>

For every [=interface=] declared with the [{{Global}}] [=extended attribute=]
that [=support named properties|supports named properties=],
there will exist an object known as the <dfn id="dfn-named-properties-object" export>named properties object</dfn>
for that interface on which named properties are exposed.

<div algorithm>
    The [=named properties object=] for a given [=interface=] |interface| and [=Realm=] |realm|,
    is <dfn lt="create a named properties object">created</dfn> as follows:

    1.  Let |proto| be null.
    1.  If |interface| is declared to inherit from another interface,
        then set |proto| to the [=interface prototype object=] in |realm| for the [=inherited interface=].
    1.  Otherwise, set |proto| to |realm|.\[[Intrinsics]].[[{{%ObjectPrototype%}}]].
    1.  Let |obj| be a newly created object.
    1.  Set |obj|'s internal methods to the definitions specified in
        [=ECMA-262 Ordinary object internal methods and internal slots=],
        unless they are specified in the the rest of [[#named-properties-object]].
    1.  Set |obj|'s remaining internal methods to the definitions specified below.
    1.  Set |obj|.\[[Prototype]] to |proto|.
    1.  Set |obj|.\[[Extensible]] to <emu-val>true</emu-val>.
    1.  Return |obj|.
</div>

The [=class string=] of a [=named properties object=]
is the concatenation of the [=interface=]’s
[=identifier=] and the string "<code>Properties</code>".


<h5 id="named-properties-object-getownproperty">\[[GetOwnProperty]]</h5>

<div algorithm="to invoke the internal [[GetOwnProperty]] method of named properties object">

    When the \[[GetOwnProperty]] internal method of a [=named properties object=] |O|
    is called with property key |P|, the following steps are taken:

    1.  Let |A| be the [=interface=] for the [=named properties object=] |O|.
    1.  Let |object| be |O|.\[[Realm]]'s [=Realm/global object=].
    1.  Assert: |object| [=implements=] |A|.
    1.  If the result of running the [=named property visibility algorithm=] with
        property name |P| and object |object| is true, then:
        1.  Let |operation| be the operation used to declare the named property getter.
        1.  Let |value| be an uninitialized variable.
        1.  If |operation| was defined without an [=identifier=], then
            set |value| to the result of performing the steps listed in the interface description to
            [=determine the value of a named property=]
            with |P| as the name.
        1.  Otherwise, |operation| was defined with an identifier.  Set |value| to the result
            of performing the steps listed in the description of |operation| with |P| as the only argument value.
        1.  Let |desc| be a newly created [=Property Descriptor=] with no fields.
        1.  Set |desc|.\[[Value]] to the result of [=converted to an ECMAScript value|converting=]
            |value| to an ECMAScript value.
        1.  If |A| [=implements=] an interface with the
            [{{LegacyUnenumerableNamedProperties}}]
            [=extended attribute=],
            then set |desc|.\[[Enumerable]] to <emu-val>false</emu-val>,
            otherwise set it to <emu-val>true</emu-val>.
        1.  Set |desc|.\[[Writable]] to <emu-val>true</emu-val> and
            |desc|.\[[Configurable]] to <emu-val>true</emu-val>.
        1.  Return |desc|.
    1.  Return <a abstract-op>OrdinaryGetOwnProperty</a>(|O|, |P|).
</div>


<h5 id="named-properties-object-defineownproperty">\[[DefineOwnProperty]]</h5>

<div algorithm="to invoke the [[DefineOwnProperty]] internal method of named properties object">

    When the \[[DefineOwnProperty]] internal method of a [=named properties object=] is called,
    the following steps are taken:

    1.  Return <emu-val>false</emu-val>.
</div>

<h5 id="named-properties-object-delete">\[[Delete]]</h5>

<div algorithm="to invoke the [[Delete]] internal method of named properties object">

    When the \[[Delete]] internal method of a [=named properties object=] is called,
    the following steps are taken:

    1.  Return <emu-val>false</emu-val>.
</div>


<h5 id="named-properties-object-setprototypeof">\[[SetPrototypeOf]]</h5>

<div algorithm="to invoke the [[SetPrototypeOf]] internal method of a named properties object">

    When the \[[SetPrototypeOf]] internal method of a [=named properties object=] |O| is called with
    ECMAScript language value |V|, the following step is taken:

    1.  Return [=?=] <a abstract-op>SetImmutablePrototype</a>(|O|, |V|).

</div>


<h5 id="named-properties-object-preventextensions">\[[PreventExtensions]]</h5>

<div algorithm="to invoke the [[PreventExtensions]] internal method of named properties object">

    When the \[[PreventExtensions]] internal method of a [=named properties object=] is called,
    the following steps are taken:

    1.  Return <emu-val>false</emu-val>.

    Note: this keeps [=named properties object=] extensible by
    making \[[PreventExtensions]] fail.
</div>


<h4 id="es-constants">Constants</h4>

[=Constants=] are exposed on [=interface objects=],
[=legacy callback interface objects=],
[=interface prototype objects=], and
on the single object that [=implements=] the interface,
when an interface is declared with the [{{Global}}] [=extended attribute=].

<div algorithm>
    To <dfn>define the constants</dfn> of [=interface=] or [=callback interface=] |definition| on
    |target|, given [=Realm=] |realm|, run the following steps:

    1.  [=list/For each=] [=constant=] |const| that is a [=member=] of |definition|:
        1.  If |const| is not [=exposed=] in |realm|, then [=iteration/continue=].
        1.  Let |value| be the result of [=converted to an ECMAScript value|converting=]
            |const|’s IDL value to an ECMAScript value.
        1.  Let |desc| be the PropertyDescriptor{\[[Writable]]: <emu-val>false</emu-val>,
            \[[Enumerable]]: <emu-val>true</emu-val>, \[[Configurable]]: <emu-val>false</emu-val>,
            \[[Value]]: |value|}.
        1.  Let |id| be |const|'s [=identifier=].
        1.  Perform [=!=] <a abstract-op>DefinePropertyOrThrow</a>(|target|, |id|, |desc|).
</div>


<h4 id="es-attributes">Attributes</h4>

[=Static attributes=] are exposed on the [=interface object=].
[=Regular attributes=] are exposed on the [=interface prototype object=],
unless the attribute is [=unforgeable=] or
if the interface was declared with the [{{Global}}] [=extended attribute=],
in which case they are exposed on every object that [=implements=] the interface.

<div algorithm>
    To <dfn>define the regular attributes</dfn> of [=interface=] or [=namespace=] |definition| on |target|,
    given [=Realm=] |realm|, run the following steps:

    1.  Let |attributes| be the [=list=] of [=regular attributes=] that are [=members=] of |definition|.
    1.  [=list/Remove=] from |attributes| all the [=attributes=] that are [=unforgeable=].
    1.  [=Define the attributes=] |attributes| of |definition| on |target| given |realm|.
</div>

<div algorithm>
    To <dfn>define the static attributes</dfn> of [=interface=] or [=namespace=] |definition| on |target|,
    given [=Realm=] |realm|, run the following steps:

    1.  Let |attributes| be the [=list=] of [=static attributes=] that are [=members=] of |definition|.
    1.  [=Define the attributes=] |attributes| of |definition| on |target| given |realm|.
</div>

<div algorithm>
    To <dfn>define the unforgeable regular attributes</dfn> of [=interface=] or [=namespace=] |definition| on |target|,
    given [=Realm=] |realm|, run the following steps:

    1.  Let |attributes| be the [=list=] of [=unforgeable=] [=regular attributes=] that are [=members=] of |definition|.
    1.  [=Define the attributes=] |attributes| of |definition| on |target| given |realm|.
</div>

<div algorithm>
    To <dfn>define the attributes</dfn> |attributes| of [=interface=] or [=namespace=] |definition| on |target|
    given [=Realm=] |realm|, run the following steps:

    1.  [=list/For each=] [=attribute=] |attr| of |attributes|:
        1.  If |attr| is not [=exposed=] in |realm|, then [=iteration/continue=].
        1.  Let |getter| be the result of creating an [=attribute getter=]
            given |attr|, |definition|, and |realm|.
        1.  Let |setter| be the result of creating an [=attribute setter=]
            given |attr|, |definition|, and |realm|.

            Note: the algorithm to create an [=attribute setter=]
            returns <emu-val>undefined</emu-val> if |attr| is [=read only=].
        1.  Let |configurable| be <emu-val>false</emu-val> if |attr| is [=unforgeable=]
            and <emu-val>true</emu-val> otherwise.
        1.  Let |desc| be the PropertyDescriptor{\[[Get]]: |getter|, \[[Set]]: |setter|,
            \[[Enumerable]]: <emu-val>true</emu-val>, \[[Configurable]]: |configurable|}.
        1.  Let |id| be |attr|'s [=identifier=].
        1.  Perform [=!=] <a abstract-op>DefinePropertyOrThrow</a>(|target|, |id|, |desc|).

</div>

<div algorithm>

    The <dfn id="dfn-attribute-getter" export>attribute getter</dfn> is created as follows, given an
    [=attribute=] |attribute|, a [=namespace=] or [=interface=] |target|, and a [=Realm=] |realm|:

    1.  Let |steps| be the following series of steps:
        1.  Try running the following steps:
            1.  Let |idlObject| be null.
            1.  If |target| is an [=interface=], and |attribute| is a [=regular attribute=]:
                1.  Let |esValue| be the <emu-val>this</emu-val> value, if it is not
                    <emu-val>null</emu-val> or <emu-val>undefined</emu-val>, or |realm|'s
                    [=Realm/global object=] otherwise.
                    (This will subsequently cause a {{ECMAScript/TypeError}} in a few steps, if
                    the global object does not implement |target| and [{{LenientThis}}] is not
                    specified.)
                    <!-- https://www.w3.org/Bugs/Public/show_bug.cgi?id=18547#c9 -->
                1.  If |esValue| [=is a platform object=], then [=perform a security check=],
                    passing |esValue|, |attribute|'s [=identifier=], and "getter".
                1.  If |esValue| does not [=implement=] |target|, then:
                    1.  If |attribute| was specified with the [{{LenientThis}}]
                        [=extended attribute=], then return <emu-val>undefined</emu-val>.
                    1.  Otherwise, [=ECMAScript/throw=] a {{ECMAScript/TypeError}}.
                1.  Set |idlObject| to the IDL [=interface type=] value that represents a reference
                    to |esValue|.
            1.  Let |R| be the result of [=get the underlying value|getting the underlying value=]
                of |attribute| given |idlObject|.
            1.  Return the result of [=converted to an ECMAScript value|converting=] |R| to an
                ECMAScript value of the type |attribute| is declared as.

        And then, if <a lt="an exception was thrown">an exception |E| was thrown</a>:

        1.  If |attribute|'s type is a [=promise type=], then return
            [=!=] <a abstract-op>Call</a>({{%Promise_reject%}}, {{%Promise%}}, «|E|»).
        1.  Otherwise, end these steps and allow the exception to propagate.
    1.  Let |F| be [=!=] <a abstract-op>CreateBuiltinFunction</a>(|steps|, « », |realm|).
    1.  Let |name| be the string "<code>get </code>" prepended to |attribute|'s [=identifier=].
    1.  Perform [=!=] <a abstract-op>SetFunctionName</a>(|F|, |name|).
    1.  Perform [=!=] <a abstract-op>SetFunctionLength</a>(|F|, 0).
    1.  Return |F|.

</div>

<div algorithm>

    The <dfn id="dfn-attribute-setter" export>attribute setter</dfn> is created as follows, given an
    [=attribute=] |attribute|, a [=namespace=] or [=interface=] |target|, and a [=Realm=] |realm|:

    1.  If |target| is a [=namespace=]:
        1. Assert: |attribute| is [=read only=].
        1. Return <emu-val>undefined</emu-val>.
    1.  If |attribute| is [=read only=] and does not have a
        [{{LenientSetter}}], [{{PutForwards}}] or [{{Replaceable}}] [=extended attribute=], return
        <emu-val>undefined</emu-val>; there is no [=attribute setter=] function.
    1.  Assert: |attribute|'s type is not a [=promise type=].
    1.  Let |steps| be the following series of steps:
        1.  If no arguments were passed, then [=ECMAScript/throw=] a {{ECMAScript/TypeError}}.
        1.  Let |V| be the value of the first argument passed.
        1.  Let |id| be |attribute|'s [=identifier=].
        1.  Let |idlObject| be null.
        1.  If |attribute| is a [=regular attribute=]:
            1.  Let |esValue| be the <emu-val>this</emu-val> value, if it is not
                <emu-val>null</emu-val> or <emu-val>undefined</emu-val>, or |realm|'s
                [=Realm/global object=] otherwise.
                (This will subsequently cause a {{ECMAScript/TypeError}} in a few steps, if
                the global object does not implement |target| and [{{LenientThis}}] is not
                specified.)
                <!-- https://www.w3.org/Bugs/Public/show_bug.cgi?id=18547#c9 -->
            1.  If |esValue| [=is a platform object=], then [=perform a security check=], passing
                |esValue|, |id|, and "setter".
            1.  Let |validThis| be true if |esValue| [=implements=] |target|, or false otherwise.
            1.  If |validThis| is false and |attribute| was not specified with the [{{LenientThis}}]
                [=extended attribute=], then [=ECMAScript/throw=] a {{ECMAScript/TypeError}}.
            1.  If |attribute| is declared with the [{{Replaceable}}] extended attribute, then:
                1.  Perform [=?=] <a abstract-op>CreateDataProperty</a>(|esValue|, |id|, |V|).
                1.  Return <emu-val>undefined</emu-val>.
            1.  If |validThis| is false, then return <emu-val>undefined</emu-val>.
            1.  If |attribute| is declared with a [{{LenientSetter}}] extended attribute, then
                return <emu-val>undefined</emu-val>.
            1.  If |attribute| is declared with a [{{PutForwards}}] extended attribute, then:
                1.  Let |Q| be [=?=] <a abstract-op>Get</a>(|esValue|, |id|).
                1.  If <a abstract-op>Type</a>(|Q|) is not Object, then [=ECMAScript/throw=] a
                    {{ECMAScript/TypeError}}.
                1.  Let |forwardId| be the identifier argument of the [{{PutForwards}}] extended
                    attribute.
                1.  Perform [=?=] <a abstract-op>Set</a>(|Q|, |forwardId|, |V|, <emu-val>true</emu-val>).
                1.  Return <emu-val>undefined</emu-val>.
            1.  Set |idlObject| to the IDL [=interface type=] value that represents a reference
                to |esValue|.
        1.  Let |idlValue| be determined as follows:

            <dl class="switch">
                <dt>|attribute|'s type is an [=enumeration=]</dt>
                <dd>
                    1.  Let |S| be [=?=] <a abstract-op>ToString</a>(|V|).
                    1.  If |S| is not one of the [=enumeration values|enumeration’s values=], then
                        return <emu-val>undefined</emu-val>.
                    1.  Otherwise, |idlValue| is the enumeration value equal to |S|.
                </dd>

                <dt>Otherwise</dt>
                <dd>
                    |idlValue| is the result of [=converted to an IDL value|converting=] |V| to an
                    IDL value of |attribute|'s type.
                </dd>
            </dl>

        1.  Perform the actions listed in the description of |attribute| that occur on setting,
            with |idlValue| as <b>[=the given value=]</b> and
            |idlObject| as <b>[=this=]</b> if it is not null.
        1.  Return <emu-val>undefined</emu-val>
    1.  Let |F| be [=!=] <a abstract-op>CreateBuiltinFunction</a>(|steps|, « », |realm|).
    1.  Let |name| be the string "<code>set </code>" prepended to |id|.
    1.  Perform [=!=] <a abstract-op>SetFunctionName</a>(|F|, |name|).
    1.  Perform [=!=] <a abstract-op>SetFunctionLength</a>(|F|, 1).
    1. Return |F|.
</div>

Note: Although there is only a single property for an IDL attribute, since
accessor property getters and setters are passed a <b>[=this=]</b>
value for the object on which property corresponding to the IDL attribute is
accessed, they are able to expose instance-specific data.

Note: Attempting to assign to a property corresponding to a
[=read only=] [=attribute=]
results in different behavior depending on whether the script doing so is in strict mode.
When in strict mode, such an assignment will result in a {{ECMAScript/TypeError}}
being thrown.  When not in strict mode, the assignment attempt will be ignored.


<h4 id="es-operations">Operations</h4>

For each unique [=identifier=] of an [=exposed=] [=operation=] defined on the [=interface=],
there exist a corresponding property.
[=Static operations=] are exposed of the [=interface object=].
[=Regular operations=] are exposed on the [=interface prototype object=],
unless the operation is [=unforgeable=] or
the interface was declared with the [{{Global}}] [=extended attribute=],
in which case they are exposed on every object that [=implements=] the interface.

<div algorithm>
    To <dfn>define the regular operations</dfn> of [=interface=] or [=namespace=] |definition| on |target|, given [=Realm=] |realm|,
    run the following steps:

    1.  Let |operations| be the [=list=] of [=regular operations=] that are [=members=] of |definition|.
    1.  [=list/Remove=] from |operations| all the [=operations=] that are [=unforgeable=].
    1.  [=Define the operations=] |operations| of |definition| on |target| given |realm|.
</div>

<div algorithm>
    To <dfn>define the static operations</dfn> of [=interface=] or [=namespace=] |definition| on |target|, given [=Realm=] |realm|,
    run the following steps:

    1.  Let |operations| be the [=list=] of [=static operations=] that are [=members=] of |definition|.
    1.  [=Define the operations=] |operations| of |definition| on |target| given |realm|.
</div>

<div algorithm>
    To <dfn>define the unforgeable regular operations</dfn> of [=interface=] or [=namespace=] |definition| on |target|, given [=Realm=] |realm|,
    run the following steps:

    1.  Let |operations| be the [=list=] of [=unforgeable=] [=regular operations=] that are [=members=] of |definition|.
    1.  [=Define the operations=] |operations| of |definition| on |target| given |realm|.
</div>

<div algorithm>
    To <dfn>define the operations</dfn> |operations| of [=interface=] or [=namespace=] |definition| on |target|,
    given [=Realm=] |realm|, run the following steps:

    1.  [=list/For each=] [=operation=] |op| of |operations|:
        1.  If |op| is not [=exposed=] in |realm|, then [=iteration/continue=].
        1.  Let |method| be the result of [=creating an operation function=]
            given |op|, |definition|, and |realm|.
        1.  Let |modifiable| be <emu-val>false</emu-val> if |op| is [=unforgeable=]
            and <emu-val>true</emu-val> otherwise.
        1.  Let |desc| be the PropertyDescriptor{\[[Value]]: |method|,
            \[[Writable]]: |modifiable|, \[[Enumerable]]: <emu-val>true</emu-val>,
            \[[Configurable]]: |modifiable|}.
        1.  Let |id| be |op|'s [=identifier=].
        1.  Perform [=!=] <a abstract-op>DefinePropertyOrThrow</a>(|target|, |id|, |desc|).
</div>

<div algorithm>
    To <dfn id="dfn-create-operation-function" lt="creating an operation function">create an operation function</dfn>,
    given an [=operation=] |op|, a [=namespace=] or [=interface=] |target|, and a [=Realm=] |realm|:

    1.  Let |id| be |op|'s [=identifier=].
    1.  Let |steps| be the following series of steps, given function argument
        values |args|:
        1.  Try running the following steps:
            1.  Let |idlObject| be null.
            1.  If |target| is an [=interface=], and |op| is not a [=static operation=]:
                1.  Let |esValue| be the <emu-val>this</emu-val> value, if it is not
                    <emu-val>null</emu-val> or <emu-val>undefined</emu-val>, or |realm|'s
                    [=Realm/global object=] otherwise.
                    (This will subsequently cause a {{ECMAScript/TypeError}} in a few steps, if
                    the global object does not implement |target| and [{{LenientThis}}] is not
                    specified.)
                    <!-- https://www.w3.org/Bugs/Public/show_bug.cgi?id=18547#c9 -->
                1.  If |esValue| [=is a platform object=], then [=perform a security check=],
                    passing |esValue|, |id|, and "method".
                1.  If |esValue| does not [=implement=] the interface |target|,
                    [=ECMAScript/throw=] a {{ECMAScript/TypeError}}.
                1.  Set |idlObject| to the IDL [=interface type=] value that represents a reference
                    to |esValue|.
            1.  Let |n| be the [=list/size=] of |args|.
            1.  [=Compute the effective overload set=]  for [=regular operations=] (if |op| is a
                regular operation) or for [=static operations=] (if |op| is a static operation)
                with [=identifier=] |id| on |target| and with argument count |n|, and let |S| be
                the result.
            1.  Let &lt;|operation|, |values|&gt; be the result of passing
                |S| and |args| to the [=overload resolution algorithm=].
            1.  Let |R| be <emu-val>null</emu-val>.
            1.  If |operation| is declared with a [{{Default}}] [=extended attribute=],
                then:
                1.  Set |R| be the result of performing the actions listed in
                    |operation|'s [=corresponding default operation=],
                    with |values| as the argument values
                    and |idlObject| as <b>[=this=]</b> if it is not null.
            1.  Otherwise:
                1.  Set |R| be the result of performing the actions listed in the
                    description of |operation|,
                    with |values| as the argument values
                    and |idlObject| as <b>[=this=]</b> if it is not null.
            1.  Return |R|, [=converted to an ECMAScript value=].

                Issue(heycam/webidl#674): |R| is assumed to be an IDL value of the type |op| is declared to return.

        And then, if <a lt="an exception was thrown">an exception |E| was thrown</a>:

        1.  If |op| has a [=return type=]
            that is a [=promise type=], then return
            [=!=] <a abstract-op>Call</a>({{%Promise_reject%}}, {{%Promise%}}, «|E|»).
        1.  Otherwise, end these steps and allow the exception to propagate.
    1.  Let |F| be [=!=] <a abstract-op>CreateBuiltinFunction</a>(|steps|, « », |realm|).
    1.  Perform [=!=] <a abstract-op>SetFunctionName</a>(|F|, |id|).
    1.  [=Compute the effective overload set=]  for [=regular operations=] (if |op| is a regular
        operation) or for [=static operations=] (if |op| is a static operation) with [=identifier=]
        |id| on |target| and with argument count 0, and let |S| be the result.
    1.  Let |length| be the length of the shortest argument list in the entries in |S|.
    1.  Perform [=!=] <a abstract-op>SetFunctionLength</a>(|F|, |length|).
    1.  Return |F|.
</div>


<h5 id="es-default-operations">Default operations</h5>

Only [=regular operations=] which have a <dfn>corresponding default operation</dfn> defined below
may be declared with a [{{Default}}] [=extended attribute=].


<h6 id="es-default-tojson">Default toJSON operation</h5>

The [=corresponding default operation=] of the <code>toJSON</code> operation is the [=default toJSON operation=].

The [=return type=] of the [=default toJSON operation=] must be {{object}}.

<div algorithm>

    To invoke the <dfn export>default toJSON operation</dfn> of [=interface=] |I|,
    run the the following steps:

    1.  Let |map| be a new [=ordered map=].
    1.  Let |stack| be the result of [=create an inheritance stack|creating an inheritance stack=]
        for [=interface=] |I|.
    1.  Invoke [=collect attribute values of an inheritance stack=] on <b>this</b>,
        passing it |stack| and |map| as arguments.
    1.  Let |result| be [=!=] <a abstract-op>ObjectCreate</a>({{%ObjectPrototype%}}).
    1.  [=map/For each=] |key| → |value| of |map|,
        1.  Let |k| be |key| [=converted to an ECMAScript value=].
        1.  Let |v| be |value| [=converted to an ECMAScript value=].
        1.  Perform [=!=] <a abstract-op>CreateDataProperty</a>(|result|, |k|, |v|).
    1.  Return |result|.
</div>

<div algorithm>

    To invoke the <dfn>collect attribute values of an inheritance stack</dfn> abstract operation
    with [=stack=] |stack| and [=ordered map=] |map| as arguments,
    run the the following steps:

    1.  Let |I| be the result of [=stack/pop|popping=] from |stack|.
    1.  Invoke [=collect attribute values=] on <b>this</b>,
        passing it |I| and |map| as arguments.
    1.  If |stack| [=stack/is not empty=],
        then invoke [=collect attribute values of an inheritance stack=] on <b>this</b>,
        passing it |stack| and |map| as arguments.
</div>

<div algorithm>

    To invoke the <dfn>collect attribute values</dfn> abstract operation
    with [=interface=] |I| and [=ordered map=] |map| as arguments,
    run the the following steps:

    1.  If a <code>toJSON</code> operation with a [{{Default}}] [=extended attribute=] is declared on |I|, then
        [=list|for each=] [=exposed=] [=regular attribute=] |attr|
        that is an [=interface member=] of |I|, in order:
        1.  Let |id| be the [=identifier=] of |attr|.
        1.  Let |value| be the result of [=get the underlying value|getting the underlying value=]
            of |attr| given <b>this</b>.
        1.  If |value| is a [=JSON type=], then [=map/set=] |map|[|id|] to |value|.

</div>

<div algorithm>

    To <dfn>create an inheritance stack</dfn> for [=interface=] |I|,
    run the the following steps:

    1.  Let |stack| be a new [=stack=].
    1.  [=stack/Push=] |I| onto |stack|.
    1.  [=iteration/While=] |I| [=interface/inherits=] from an [=interface=],
        1.  Let |I| be that [=interface=].
        1.  [=stack/Push=] |I| onto |stack|.
    1.  Return |stack|.
</div>

<div class=example id=example-tojson-default-inheritance-and-mixins>

    The following [=IDL fragment=] defines a number of [=interfaces=],
    which are [=inherited interfaces=] of <code class="idl">A</code>,
    and [=interface mixins=], which are [=included=] by <code class="idl">A</code> or
    by <code class="idl">A</code>'s [=inherited interfaces=],
    as show in the below inheritance tree.

    <pre>
             C* - M4
             |
             B - M3
             |
        M1 - A - M2*
    </pre>

    [=Interfaces=] and [=interface mixins=] marked with an asterisk ("*")
    declare a <code>toJSON</code> [=operation=]
    with a [{{Default}}] [=extended attribute=].

    <pre class=webidl>
        [Exposed=Window]
        interface A : B {
          attribute DOMString a;
        };

        [Exposed=Window]
        interface B : C {
          attribute DOMString b;
        };

        [Exposed=Window]
        interface C {
          [Default] object toJSON();
          attribute DOMString c;
        };

        interface mixin M1 {
          attribute DOMString m1;
        };

        interface mixin M2 {
          [Default] object toJSON();
          attribute DOMString m2;
        };

        interface mixin M3 {
          attribute DOMString m3;
        };

        interface mixin M4 {
          attribute DOMString m4;
        };

        A includes M1;
        A includes M2;
        B includes M3;
        C includes M4;
    </pre>

    Calling the <code>toJSON()</code> method of an object
    implementing interface <code class="idl">A</code> defined above
    would return the following JSON object:

    <pre highlight=json>
    {
        "a": "...",
        "m1": "...",
        "m2": "...",
        "c": "...",
        "m4": "..."
    }
    </pre>

    An object implementing interface <code class="idl">B</code> would return:

    <pre highlight=json>
    {
        "c": "...",
        "m4": "..."
    }
    </pre>
</div>

<h5 id="es-stringifier">Stringifiers</h5>

If the [=interface=] has an [=exposed=] [=stringifier=],
then there must exist a property with the following characteristics:

*   The name of the property is "<code>toString</code>".
*   If the [=stringifier=] is [=unforgeable=] on the interface
    or if the interface was declared with the [{{Global}}] [=extended attribute=],
    then the property exists on every object that [=implements=] the interface.
    Otherwise, the property exists on the [=interface prototype object=].
*   The property has attributes
    { \[[Writable]]: |B|, \[[Enumerable]]: <emu-val>true</emu-val>, \[[Configurable]]: |B| },
    where |B| is <emu-val>false</emu-val> if the stringifier is [=unforgeable=] on the interface,
    and <emu-val>true</emu-val> otherwise.
*   <div algorithm="to invoke the toString method of interfaces">

        The value of the property is a [=built-in function object=], which behaves as follows:

        1.  Let |O| be the result of calling <a abstract-op>ToObject</a> on the <emu-val>this</emu-val> value.
        1.  If |O| [=is a platform object=],
            then [=perform a security check=], passing:
            *   the platform object |O|,
            *   the [=identifier=] of the [=stringifier=], and
            *   the type "<code>method</code>".
        1.  If |O| does not [=implement=] the [=interface=]
            on which the stringifier was declared, then [=ECMAScript/throw=] a {{ECMAScript/TypeError}}.
        1.  Let |V| be an uninitialized variable.
        1.  Depending on where <code>stringifier</code> was specified:
            <dl class="switch">
                 :  on an [=attribute=]
                 :: Set |V| to the result of performing the actions listed in the description of the attribute that occur when getting
                    (or those listed in the description of the inherited attribute, if this attribute is declared to
                    [=inherit its getter=]),
                    with |O| as the object.
                 :  on an [=operation=] with an identifier
                 :: Set |V| to the result of performing the actions listed in the description
                    of the operation, using |O| as the <emu-val>this</emu-val> value
                    and passing no arguments.
                 :  on an [=operation=] with no identifier
                 :: Set |V| to the result of performing the [=stringification behavior=]
                    of the interface.
            </dl>
        1.  Return the result of [=converted to an ECMAScript value|converting=] |V| to a String value.
    </div>
*   The value of the [=function object=]’s <code class="idl">length</code>
    property is the Number value <emu-val>0</emu-val>.
*   The value of the [=function object=]’s <code class="idl">name</code>
    property is the String value "<code>toString</code>".


<h4 id="es-iterators">Common iterator behavior</h4>


<h5 id="es-iterator">@@iterator</h5>

If the [=interface=] has any of the following:

*   an [=iterable declaration=]
*   an [=indexed property getter=]
*   a [=maplike declaration=]
*   a [=setlike declaration=]

then a property must exist
whose name is the {{@@iterator}} symbol, with attributes
{ \[[Writable]]: <emu-val>true</emu-val>, \[[Enumerable]]: <emu-val>false</emu-val>, \[[Configurable]]: <emu-val>true</emu-val> }
and whose value is a [=function object=].

The location of the property is determined as follows:

*   If the interface was declared with the [{{Global}}] [=extended attribute=],
    then the property exists on the single object that [=implements=] the interface.
*   Otherwise, the property exists solely on the interface’s [=interface prototype object=].

If the interface defines an [=indexed property getter=],
then the [=function object=] is {{%ArrayProto_values%}}.

<div algorithm="to invoke the @@iterator property of interfaces with a pair iterator">

    If the interface has a [=pair iterator=], then the [=function object=] is a [=built-in function object=] that,
    when invoked, must behave as follows:

    1.  Let |object| be the result of calling <a abstract-op>ToObject</a> on the <emu-val>this</emu-val> value.
    1.  If |object| [=is a platform object=],
        then [=perform a security check=], passing:
        *   the platform object |object|,
        *   the identifier "<code>@@iterator</code>", and
        *   the type "<code>method</code>".
    1.  Let |interface| be the [=interface=]
        the [=iterable declaration=] is on.
    1.  If |object| does not [=implement=] |interface|,
        then [=ECMAScript/throw=] a {{ECMAScript/TypeError}}.
    1.  Let |iterator| be a newly created [=default iterator object=]
        for |interface| with |object| as its target and iterator kind "<code>key+value</code>".
    1.  Return |iterator|.
</div>

<div algorithm="to invoke the @@iterator property of interfaces with maplike or setlike declarations">

    If the interface has a [=maplike declaration=] or [=setlike declaration=],
    then the [=function object=] is a [=built-in function object=] that,
    when invoked, must behave as follows:

    1.  Let |object| be the result of calling <a abstract-op>ToObject</a> on the <emu-val>this</emu-val> value.
    1.  If |object| [=is a platform object=],
        then [=perform a security check=], passing:
        *   the platform object |object|,
        *   the identifier "<code>@@iterator</code>", and
        *   the type "<code>method</code>".
    1.  If |object| does not [=implement=] the [=interface=]
        on which the [=maplike declaration=]
        or [=setlike declaration=] is defined,
        then [=ECMAScript/throw=] a {{ECMAScript/TypeError}}.
    1.  If the interface has a [=maplike declaration=], then:
        1.  Let |backing| be the value of the \[[BackingMap]] [=internal slot=] of |object|.
        1.  Return <a abstract-op>CreateMapIterator</a>(|backing|, "<code>key+value</code>").
    1.  Otherwise:
        1.  Let |backing| be the value of the \[[BackingSet]] [=internal slot=] of |object|.
        1.  Return <a abstract-op>CreateSetIterator</a>(|backing|, "<code>value</code>").
</div>

The value of the {{@@iterator}} [=function object=]’s <code class="idl">length</code>
property is the Number value <emu-val>0</emu-val>.

The value of the {{@@iterator}} [=function object=]’s <code class="idl">name</code> property
is the String value "<code>entries</code>"
if the interface has a [=pair iterator=] or a [=maplike declaration=]
and the String "<code>values</code>"
if the interface has a [=setlike declaration=].


<h5 id="es-async-iterator">@@asyncIterator</h5>

If the [=interface=] has an [=asynchronously iterable declaration=], then a property must exist
whose name is the {{@@asyncIterator}} symbol, with attributes
{ \[[Writable]]: <emu-val>true</emu-val>, \[[Enumerable]]: <emu-val>false</emu-val>, \[[Configurable]]: <emu-val>true</emu-val> }
and whose value is a [=function object=].

The location of the property is determined as follows:

*   If the interface was declared with the [{{Global}}] [=extended attribute=],
    then the property exists on the single object that [=implements=] the interface.
*   Otherwise, the property exists solely on the interface’s [=interface prototype object=].

<div algorithm="to invoke the @@asyncIterator property">

    The [=function object=] is a [=built-in function object=] that, when invoked, must behave as
    follows:

    1.  Let |object| be the result of calling [$ToObject$] on the <emu-val>this</emu-val> value.
    1.  If |object| [=is a platform object=], then [=perform a security check=], passing:
        *   the platform object |object|,
        *   the identifier "<code>@@asyncIterator</code>", and
        *   the type "<code>method</code>".
    1.  Let |interface| be the [=interface=] on which the [=asynchronously iterable declaration=]
        is declared.
    1.  If |object| does not [=implement=] |interface|, then [=ECMAScript/throw=] a
        {{ECMAScript/TypeError}}.
    1.  Let |iterator| be a newly created [=default asynchronous iterator object=] for |interface|
        with |object| as its [=default asynchronous iterator object/target=],
        "<code>key+value</code>" as its [=default asynchronous iterator object/kind=], and
        [=default asynchronous iterator object/is finished=] set to false.
    1.  Run the [=asynchronous iterator initialization steps=] for |interface| with |object| and
        |iterator|, if any such steps exist.
    1.  Return |iterator|.
</div>

The value of the {{@@asyncIterator}} [=function object=]’s <code class="idl">length</code> property
is the Number value <emu-val>0</emu-val>.

The value of the {{@@asyncIterator}} [=function object=]’s <code class="idl">name</code> property
is the String value "<code>entries</code>".


<h5 id="es-forEach">forEach</h5>

If the [=interface=] has any of the following:

*   an [=iterable declaration=]
*   a [=maplike declaration=]
*   a [=setlike declaration=]

then a <code class="idl">forEach</code> data property must exist with attributes
{ \[[Writable]]: <emu-val>true</emu-val>, \[[Enumerable]]: <emu-val>true</emu-val>, \[[Configurable]]: <emu-val>true</emu-val> }
and whose value is a [=function object=].

The location of the property is determined as follows:

*   If the interface was declared with the [{{Global}}] [=extended attribute=],
    then the property exists on the single object that [=implements=] the interface.
*   Otherwise, the property exists solely on the interface’s [=interface prototype object=].

If the interface defines an [=indexed property getter=],
then the [=function object=] is {{%ArrayProto_forEach%}}.

<div algorithm="to invoke the forEach method of interfaces with indexed properties">

    If the interface has a [=pair iterator=],
    then the method must have the same behavior,
    when invoked with argument |callback| and optional argument |thisArg|,
    as one that would exist assuming the interface had this [=operation=]
    instead of the [=iterable declaration=]:

    <pre highlight="webidl">
      [Exposed=Window]
      interface Iterable {
        void forEach(Function callback, optional any thisArg);
      };
    </pre>

    with the following prose definition:

    1.  Let |pairs| be the list of [=value pairs to iterate over=].
    1.  Let |i| be 0.
    1.  While |i| is less than the length of |pairs|:
        1.  Let |pair| be the entry in |pairs| at index |i|.
        1.  Let |key| be |pair|’s [=value pair/key=].
        1.  Let |value| be |pair|’s [=value pair/value=].
        1.  [=Invoke=] |callback| with |thisArg|
            (or <emu-val>undefined</emu-val>, if the argument was not supplied)
            as the [=callback this value=] and |value|, |key| and <b>this</b> as its arguments.
        1.  Update |pairs| to the current list of [=value pairs to iterate over=].
        1.  Set |i| to |i| + 1.
</div>

<div algorithm="to invoke the forEach method of interfaces with maplike or setlike declarations">

    If the interface has a [=maplike declaration=] or [=setlike declaration=] then
    the method, when invoked, must behave as follows:

    1.  Let |object| be the result of calling <a abstract-op>ToObject</a> on the <emu-val>this</emu-val> value.
    1.  If |object| [=is a platform object=],
        then [=perform a security check=], passing:
        *   the platform object |object|,
        *   the identifier "<code>forEach</code>", and
        *   the type "<code>method</code>".
    1.  Let |interface| be the [=interface=]
        on which the [=maplike declaration=]
        or [=setlike declaration=] is declared.
    1.  If |object| does not [=implement=] |interface|,
        then [=ECMAScript/throw=] a {{ECMAScript/TypeError}}.
    1.  Let |callbackFn| be the value of the first argument passed to the function, or <emu-val>undefined</emu-val> if the argument was not supplied.
    1.  If <a abstract-op>IsCallable</a>(|callbackFn|) is <emu-val>false</emu-val>, [=ECMAScript/throw=] a {{ECMAScript/TypeError}}.
    1.  Let |thisArg| be the value of the second argument passed to the function, or <emu-val>undefined</emu-val> if the argument was not supplied.
    1.  Let |backing| be the value of the \[[BackingMap]] [=internal slot=] of |object|,
        if the interface has a [=maplike declaration=],
        or the \[[BackingSet]] [=internal slot=] of |object| otherwise.
    1.  Let |callbackWrapper| be a [=built-in function object=] that, when invoked, behaves as follows:
        1.  Let |v| and |k| be the first two arguments passed to the function.
        1.  Let |thisArg| be the <emu-val>this</emu-val> value.
        1.  Perform [=?=] <a abstract-op>Call</a>(|callbackFn|, |thisArg|, «|v|, |k|, |object|»).

        Note: The |callbackWrapper| function simply calls the incoming |callbackFn|
        with |object| as the third argument rather than its internal \[[BackingMap]] or \[[BackingSet]] object.

        <p class="issue">
            Can the script author observe that |callbackWrapper| might be a new function
            every time forEach is called?  What's the best way of specifying that there's only
            one function that has captured an environment?
        </p>
    1.  Let |forEach| be [=?=] <a abstract-op>GetMethod</a>(|backing|, "<code>forEach</code>").
    1.  If |forEach| is <emu-val>undefined</emu-val>, then [=ECMAScript/throw=] a {{ECMAScript/TypeError}}.
    1.  Perform [=?=] <a abstract-op>Call</a>(|forEach|, |backing|, «|callbackWrapper|, |thisArg|»).
    1.  Return <emu-val>undefined</emu-val>.
</div>

The value of the [=function object=]’s <code class="idl">length</code>
property is the Number value <emu-val>1</emu-val>.

The value of the [=function object=]’s <code class="idl">name</code>
property is the String value "<code>forEach</code>".


<h4 id="es-iterable">Iterable declarations</h4>


<h5 id="es-iterable-entries">entries</h5>

If the [=interface=] has an [=iterable declaration=] or an [=asynchronously iterable declaration=],
then an <code class="idl">entries</code> data property must exist with attributes
{ \[[Writable]]: <emu-val>true</emu-val>, \[[Enumerable]]: <emu-val>true</emu-val>, \[[Configurable]]: <emu-val>true</emu-val> }
and whose value is a [=function object=].

The location of the property is determined as follows:

*   If the interface was declared with the [{{Global}}] [=extended attribute=],
    then the property exists on the single object that [=implements=] the interface.
*   Otherwise, the property exists solely on the interface’s [=interface prototype object=].

If the interface has a [=value iterator=],
then the [=function object=] is {{%ArrayProto_entries%}}.

If the interface has a [=pair iterator=],
then the [=function object=] is
the value of the {{@@iterator}} property.

If the interface has an [=asynchronously iterable declaration=], then the [=function object=] is
the value of the {{@@asyncIterator}} property.

<h5 id="es-iterable-keys">keys</h5>

If the [=interface=] has an [=iterable declaration=] or an [=asynchronously iterable declaration=],
then a <code class="idl">keys</code> data property must exist with attributes
{ \[[Writable]]: <emu-val>true</emu-val>, \[[Enumerable]]: <emu-val>true</emu-val>, \[[Configurable]]: <emu-val>true</emu-val> }
and whose value is a [=function object=].

The location of the property is determined as follows:

*   If the interface was declared with the [{{Global}}] [=extended attribute=],
    then the property exists on the single object that [=implements=] the interface.
*   Otherwise, the property exists solely on the interface’s [=interface prototype object=].

If the interface has a [=value iterator=],
then the [=function object=] is {{%ArrayProto_keys%}}.

<div algorithm="to invoke the keys method of interfaces with a pair iterator">

    If the interface has a [=pair iterator=],
    then the method, when invoked, must behave as follows:

    1.  Let |object| be the result of calling <a abstract-op>ToObject</a> on the <emu-val>this</emu-val> value.
    1.  If |object| [=is a platform object=],
        then [=perform a security check=], passing:
        *   the platform object |object|,
        *   the identifier "<code>keys</code>", and
        *   the type "<code>method</code>".
    1.  Let |interface| be the [=interface=]
        on which the [=iterable declaration=] is declared.
    1.  If |object| does not [=implement=] |interface|,
        then [=ECMAScript/throw=] a {{ECMAScript/TypeError}}.
    1.  Let |iterator| be a newly created [=default iterator object=]
        for |interface| with |object| as its target and iterator kind "<code>key</code>".
    1.  Return |iterator|.
</div>

<div algorithm="to invoke the keys method of asynchronously iterable interfaces">

    If the interface has an [=asynchronously iterable declaration=], then the method, when invoked,
    must behave as follows:

    1.  Let |object| be the result of calling [$ToObject$] on the <emu-val>this</emu-val> value.
    1.  If |object| [=is a platform object=], then [=perform a security check=], passing:
        *   the platform object |object|,
        *   the identifier "<code>keys</code>", and
        *   the type "<code>method</code>".
    1.  Let |interface| be the [=interface=] on which the [=asynchronously iterable declaration=]
        is declared.
    1.  If |object| does not [=implement=] |interface|, then [=ECMAScript/throw=] a
        {{ECMAScript/TypeError}}.
    1.  Let |iterator| be a newly created [=default asynchronous iterator object=] for |interface|
        with |object| as its [=default asynchronous iterator object/target=],
        "<code>key</code>" as its [=default asynchronous iterator object/kind=], and
        [=default asynchronous iterator object/is finished=] set to false.
    1.  Run the [=asynchronous iterator initialization steps=] for |interface| with |object| and
        |iterator|, if any such steps exist.
    1.  Return |iterator|.
</div>

The value of the [=function object=]’s <code class="idl">length</code> property is the Number value <emu-val>0</emu-val>.

The value of the [=function object=]’s <code class="idl">name</code> property is the String value "<code>keys</code>".


<h5 id="es-iterable-values">values</h5>

If the [=interface=] has an [=iterable declaration=] or an [=asynchronously iterable declaration=],
then a <code class="idl">values</code> data property must exist
with attributes { \[[Writable]]: <emu-val>true</emu-val>, \[[Enumerable]]: <emu-val>true</emu-val>, \[[Configurable]]: <emu-val>true</emu-val> }
and whose value is a [=function object=].

The location of the property is determined as follows:

*   If the interface was declared with the [{{Global}}] [=extended attribute=],
    then the property exists on the single object that [=implements=] the interface.
*   Otherwise, the property exists solely on the interface’s [=interface prototype object=].

If the interface has a [=value iterator=],
then the [=function object=] is
the value of the {{@@iterator}} property.

<div algorithm="to invoke the values method of interfaces with a pair iterator">

    If the interface has a [=pair iterator=],
    then the method, when invoked, must behave as follows:

    1.  Let |object| be the result of calling <a abstract-op>ToObject</a> on the <emu-val>this</emu-val> value.
    1.  If |object| [=is a platform object=],
        then [=perform a security check=], passing:
        *   the platform object |object|,
        *   the identifier "<code>entries</code>", and
        *   the type "<code>method</code>".
    1.  Let |interface| be the [=interface=]
        on which the [=iterable declaration=] is declared.
    1.  If |object| does not [=implement=] |interface|,
        then [=ECMAScript/throw=] a {{ECMAScript/TypeError}}.
    1.  Let |iterator| be a newly created [=default iterator object=]
        for |interface| with |object| as its target and iterator kind "<code>value</code>".
    1.  Return |iterator|.
</div>

<div algorithm="to invoke the values method of asynchronously iterable interfaces">

    If the interface has an [=asynchronously iterable declaration=], then the method, when invoked,
    must behave as follows:

    1.  Let |object| be the result of calling [$ToObject$] on the <emu-val>this</emu-val> value.
    1.  If |object| [=is a platform object=], then [=perform a security check=], passing:
        *   the platform object |object|,
        *   the identifier "<code>entries</code>", and
        *   the type "<code>method</code>".
    1.  Let |interface| be the [=interface=] on which the [=asynchronously iterable declaration=]
        is declared.
    1.  If |object| does not [=implement=] |interface|, then [=ECMAScript/throw=] a
        {{ECMAScript/TypeError}}.
    1.  Let |iterator| be a newly created [=default asynchronous iterator object=] for |interface|
        with |object| as its [=default asynchronous iterator object/target=],
        "<code>value</code>" as its [=default asynchronous iterator object/kind=], and
        [=default asynchronous iterator object/is finished=] set to false.
    1.  Run the [=asynchronous iterator initialization steps=] for |interface| with |object| and
        |iterator|, if any such steps exist.
    1.  Return |iterator|.
</div>

The value of the [=function object=]’s <code class="idl">length</code> property is the Number value <emu-val>0</emu-val>.

The value of the [=function object=]’s <code class="idl">name</code> property is the String value "<code>values</code>".


<h5 id="es-default-iterator-object">Default iterator objects</h5>

A <dfn id="dfn-default-iterator-object" export>default iterator object</dfn> for a given
[=interface=], target and iteration kind
is an object whose \[[Prototype]] [=internal slot=] is the
[=iterator prototype object=]
for the [=interface=].

A [=default iterator object=]
has three internal values:

1.  its <em>target</em>, which is an object whose values are to be iterated,
1.  its <em>kind</em>, which is the iteration kind,
1.  its <em>index</em>, which is the current index into the values value to be iterated.

Note: Default iterator objects are only used for [=pair iterators=];
[=value iterators=], as they are currently
restricted to iterating over an object’s
[=support indexed properties|supported indexed properties=],
use standard ECMAScript Array iterator objects.

When a [=default iterator object=] is first created,
its index is set to 0.

[=Default iterator objects=] do not have [=class strings=]; when <code
class="idl">Object.prototype.toString()</code> is called on a [=default
iterator object=] of a given [=interface=], the [=class string=] of the
[=iterator prototype object=] of that [=interface=] is used.


<h5 id="es-iterator-prototype-object">Iterator prototype object</h5>

The <dfn id="dfn-iterator-prototype-object" export>iterator prototype object</dfn>
for a given [=interface=]
is an object that exists for every interface that has a
[=pair iterator=].  It serves as the
prototype for [=default iterator objects=]
for the interface.

The \[[Prototype]] [=internal slot=] of an [=iterator prototype object=]
must be {{%IteratorPrototype%}}.

<div algorithm>
  The <dfn>iterator result</dfn> for a [=value pair=] |pair| and a kind |kind| is given by the
  following steps:

    1.  Let |result| be a value determined by the value of |kind|:
        <dl class="switch">
             :  "<code>key</code>"
             :: 1.  Let |idlKey| be |pair|’s [=value pair/key=].
                1.  Let |key| be the result of [=converted to an ECMAScript value|converting=] |idlKey| to an ECMAScript value.
                1.  |result| is |key|.
             :  "<code>value</code>"
             :: 1.  Let |idlValue| be |pair|’s [=value pair/value=].
                1.  Let |value| be the result of [=converted to an ECMAScript value|converting=] |idlValue| to an ECMAScript value.
                1.  |result| is |value|.
             :  "<code>key+value</code>"
             :: 1.  Let |idlKey| be |pair|’s [=value pair/key=].
                1.  Let |idlValue| be |pair|’s [=value pair/value=].
                1.  Let |key| be the result of [=converted to an ECMAScript value|converting=] |idlKey| to an ECMAScript value.
                1.  Let |value| be the result of [=converted to an ECMAScript value|converting=] |idlValue| to an ECMAScript value.
                1.  Let |array| be the result of performing [$ArrayCreate$](2).
                1.  Call [$CreateDataProperty$](|array|, "<code>0</code>", |key|).
                1.  Call [$CreateDataProperty$](|array|, "<code>1</code>", |value|).
                1.  |result| is |array|.
        </dl>
    1.  Return [$CreateIterResultObject$](|result|, <emu-val>false</emu-val>).
</div>

<div algorithm="to invoke the next property of iterators">

    An [=iterator prototype object=] must have a <code class="idl">next</code> data property with attributes
    { \[[Writable]]: <emu-val>true</emu-val>, \[[Enumerable]]: <emu-val>true</emu-val>, \[[Configurable]]: <emu-val>true</emu-val> }
    and whose value is a [=built-in function object=] that behaves as follows:

    1.  Let |interface| be the [=interface=] for which the
        [=iterator prototype object=] exists.
    1.  Let |object| be the result of calling <a abstract-op>ToObject</a> on the <emu-val>this</emu-val> value.
    1.  If |object| [=is a platform object=],
        then [=perform a security check=], passing:
        *   the platform object |object|,
        *   the identifier "<code>next</code>", and
        *   the type "<code>method</code>".
    1.  If |object| is not a [=default iterator object=] for |interface|,
        then [=ECMAScript/throw=] a {{ECMAScript/TypeError}}.
    1.  Let |index| be |object|’s index.
    1.  Let |kind| be |object|’s kind.
    1.  Let |values| be the list of [=value pairs to iterate over=].
    1.  Let |len| be the length of |values|.
    1.  If |index| is greater than or equal to |len|, then
        return <a abstract-op>CreateIterResultObject</a>(<emu-val>undefined</emu-val>, <emu-val>true</emu-val>).
    1.  Let |pair| be the entry in |values| at index |index|.
    1.  Set |object|’s index to |index| + 1.
    1.  Return the [=iterator result=] for |pair| and |kind|.
</div>

The [=class string=] of an [=iterator prototype object=] for a given [=interface=]
is the result of concatenating the [=identifier=] of the [=interface=]
and the string "<code> Iterator</code>".


<h5 id="es-default-asynchronous-iterator-object">Default asynchronous iterator objects</h5>

A <dfn id="dfn-default-asynchronous-iterator-object" export>default asynchronous iterator
object</dfn> for a given [=interface=], target and iteration kind is an object whose \[[Prototype]]
[=internal slot=] is the [=asynchronous iterator prototype object=] for the [=interface=].

A [=default asynchronous iterator object=] has internal values:

*   its <dfn for="default asynchronous iterator object">target</dfn>, which is an object whose
    values are to be iterated,
*   its <dfn for="default asynchronous iterator object">kind</dfn>, which is the iteration kind,
*   its <dfn for="default asynchronous iterator object">ongoing promise</dfn>, which is a
    {{Promise}} or null,
*   its <dfn for="default asynchronous iterator object">is finished</dfn>, which is a boolean.

Note: [=Default asynchronous iterator objects=] do not have [=class strings=]; when
<code class="idl">Object.prototype.toString()</code> is called on a
[=default asynchronous iterator object=] of a given [=interface=], the [=class string=] of the
[=asynchronous iterator prototype object=] of that [=interface=] is used.


<h5 id="es-asynchronous-iterator-prototype-object">Asynchronous iterator prototype object</h5>

The
<dfn id="dfn-asynchronous-iterator-prototype-object" export>asynchronous iterator prototype object</dfn>
for a given [=interface=] is an object that exists for every interface that has an
[=asynchronously iterable declaration=].
It serves as the prototype for [=default asynchronous iterator objects=] for the interface.

The \[[Prototype]] [=internal slot=] of an [=asynchronous iterator prototype object=] must be
{{%AsyncIteratorPrototype%}}.

<div algorithm="to invoke the next property of asynchronous iterators">

    An [=asynchronous iterator prototype object=] must have a <code class="idl">next</code> data
    property with attributes { \[[Writable]]: <emu-val>true</emu-val>,
    \[[Enumerable]]: <emu-val>true</emu-val>, \[[Configurable]]: <emu-val>true</emu-val> }
    and whose value is a [=built-in function object=] that behaves as follows:

    1.  Let |interface| be the [=interface=] for which the
        [=asynchronous iterator prototype object=] exists.

    1.  Let |thisValidationPromiseCapability| be [=!=] [$NewPromiseCapability$]({{%Promise%}}).

    1.  Let |object| be the result of calling [$ToObject$] on the
        <emu-val>this</emu-val> value.

    1.  [$IfAbruptRejectPromise$](|object|, |thisValidationPromiseCapability|).

    1.  If |object| [=is a platform object=], then [=perform a security check=], passing:
        *   the platform object |object|,
        *   the identifier "<code>next</code>", and
        *   the type "<code>method</code>".

        If this threw an exception |e|, then:
        1.  Perform [=!=] [$Call$](|thisValidationPromiseCapability|.\[[Reject]],
            <emu-val>undefined</emu-val>, « |e| »).
        1.  Return |thisValidationPromiseCapability|.\[[Promise]].

    1.  If |object| is not a [=default asynchronous iterator object=] for |interface|, then:
        1.  Let |error| be a new {{ECMAScript/TypeError}}.
        1.  Perform [=!=] [$Call$](|thisValidationPromiseCapability|.\[[Reject]],
            <emu-val>undefined</emu-val>, « |error| »).
        1.  Return |thisValidationPromiseCapability|.\[[Promise]].

    1.  Let |nextSteps| be the following steps:
        1.  Let |nextPromiseCapability| be [=!=] [$NewPromiseCapability$]({{%Promise%}}).
        1.  If |object|'s [=default asynchronous iterator object/is finished=] is true, then:
            1.  Let |result| be [$CreateIterResultObject$](<emu-val>undefined</emu-val>,
                <emu-val>true</emu-val>).
            1.  Perform [=!=] [$Call$](|nextPromiseCapability|.\[[Resolve]],
                <emu-val>undefined</emu-val>, « |result| »).
            1.  Return |nextPromiseCapability|.\[[Promise]].
        1.  Let |kind| be |object|'s [=default asynchronous iterator object/kind=].
        1.  Let |nextPromise| be the result of
            [=get the next iteration result|getting the next iteration result=] with |object|'s
            [=default asynchronous iterator object/target=] and |object|.
        1.  Let |fulfillSteps| be the following steps, given |next|:
            1.  Set |object|'s [=default asynchronous iterator object/ongoing promise=] to
                null.
            1.  If |next| is <emu-val>undefined</emu-val>, then:
                1.  Set |object|'s [=default asynchronous iterator object/is finished=] to true.
                1.  Return [=!=] [$CreateIterResultObject$](<emu-val>undefined</emu-val>,
                    <emu-val>true</emu-val>).
            1.  Otherwise:
                1.  Return the [=iterator result=] for |next| and |kind|.
        1.  Let |onFulfilled| be [=!=] [$CreateBuiltinFunction$](|fulfillSteps|, « »).
        1.  Perform [=!=] [$PerformPromiseThen$](|nextPromise|, |onFulfilled|,
            <emu-val>undefined</emu-val>, |nextPromiseCapability|).
        1.  Return |nextPromiseCapability|.\[[Promise]].

    1.  Let |promise| be |object|'s [=default asynchronous iterator object/ongoing promise=].

    1.  If |promise| is not null, then:
        1.  Let |afterOngoingPromiseCapability| be [=!=] [$NewPromiseCapability$]({{%Promise%}}).
        1.  Let |onFulfilled| be [=!=] [$CreateBuiltinFunction$](|nextSteps|, « »).
        1.  Perform [=!=] [$PerformPromiseThen$](|promise|, |onFulfilled|,
            <emu-val>undefined</emu-val>, |afterOngoingPromiseCapability|).
        1.  Set |object|'s [=default asynchronous iterator object/ongoing promise=] to
            |afterOngoingPromiseCapability|.\[[Promise]].

    1.  Otherwise:
        1.  Run |nextSteps| and set |object|'s
            [=default asynchronous iterator object/ongoing promise=] to the result.

    1.  Return |object|'s [=default asynchronous iterator object/ongoing promise=].
</div>

<div algorithm="to invoke the return property of asynchronous iterators">

    If an [=asynchronous iterator return=] algorithm is defined for the [=interface=], then the
    [=asynchronous iterator prototype object=] must have a <code class="idl">return</code> data
    property with attributes { \[[Writable]]: <emu-val>true</emu-val>,
    \[[Enumerable]]: <emu-val>true</emu-val>, \[[Configurable]]: <emu-val>true</emu-val> }
    and whose value is a [=built-in function object=], taking one argument |value|, that behaves as
    follows:

    1.  Let |interface| be the [=interface=] for which the
        [=asynchronous iterator prototype object=] exists.

    1.  Let |returnPromiseCapability| be [=!=] [$NewPromiseCapability$]({{%Promise%}}).

    1.  Let |object| be the result of calling [$ToObject$] on the
        <emu-val>this</emu-val> value.

    1.  [$IfAbruptRejectPromise$](|object|, |returnPromiseCapability|).

    1.  If |object| [=is a platform object=], then [=perform a security check=], passing:
        *   the platform object |object|,
        *   the identifier "<code>return</code>", and
        *   the type "<code>method</code>".

        If this threw an exception |e|, then:
        1.  Perform [=!=] [$Call$](|returnPromiseCapability|.\[[Reject]],
            <emu-val>undefined</emu-val>, « |e| »).
        1.  Return |returnPromiseCapability|.\[[Promise]].

    1.  If |object| is not a [=default asynchronous iterator object=] for |interface|, then:
        1.  Let |error| be a new {{ECMAScript/TypeError}}.
        1.  Perform [=!=] [$Call$](|returnPromiseCapability|.\[[Reject]],
            <emu-val>undefined</emu-val>, « |error| »).
        1.  Return |returnPromiseCapability|.\[[Promise]].

    1.  If |object|'s [=default asynchronous iterator object/ongoing promise=] is not null, then:
        1.  Let |error| be a new {{ECMAScript/TypeError}}.
        1.  Perform [=!=] [$Call$](|returnPromiseCapability|.\[[Reject]],
            <emu-val>undefined</emu-val>, « |error| »).
        1.  Return |returnPromiseCapability|.\[[Promise]].

    1.  If |object|'s [=default asynchronous iterator object/is finished=] is true, then:
        1.  Let |result| be [=!=] [$CreateIterResultObject$](|value|,
            <emu-val>true</emu-val>).
        1.  Perform [=!=] [$Call$](|returnPromiseCapability|.\[[Resolve]],
            <emu-val>undefined</emu-val>, « |result| »).
        1.  Return |returnPromiseCapability|.\[[Promise]].

    1.  Set |object|'s [=default asynchronous iterator object/is finished=] to true.

    1.  Let |returnPromise| be the result of running the [=asynchronous iterator return=] algorithm
        for |interface|, given |object|'s [=default asynchronous iterator object/target=],
        |object|, and |value|.

    1.  Let |fulfillSteps| be the following steps:
        1.  Return [=!=] [$CreateIterResultObject$](|value|, <emu-val>true</emu-val>).

    1.  Let |onFulfilled| be [=!=] [$CreateBuiltinFunction$](|fulfillSteps|, « »).

    1.  Perform [=!=] [$PerformPromiseThen$](|returnPromise|, |onFulfilled|,
        <emu-val>undefined</emu-val>, |returnPromiseCapability|).

    1.  Return |returnPromiseCapability|.\[[Promise]].
</div>

The [=class string=] of an [=asynchronous iterator prototype object=] for a given [=interface=] is
the result of concatenating the [=identifier=] of the [=interface=] and the string
"<code> AsyncIterator</code>".


<h4 id="es-maplike">Maplike declarations</h4>

Any object that [=implements=] an [=interface=]
that has a [=maplike declaration=]
must have a \[[BackingMap]] [=internal slot=], which is
initially set to a newly created {{ECMAScript/Map}} object.
This {{ECMAScript/Map}} object’s \[[MapData]] internal slot is
the object’s [=map entries=].

If an [=interface=] |A| is declared with
a [=maplike declaration=], then
there exists a number of additional properties on |A|’s
[=interface prototype object=].
These additional properties are described in the sub-sections below.

<div algorithm>

    Some of the properties below are defined to have a [=function object=] value that
    <dfn id="dfn-forwards-to-the-internal-map-object" export>forwards to the internal map object</dfn>
    for a given function name.  Such functions behave as follows when invoked:

    1.  Let |O| be the <emu-val>this</emu-val> value.
    1.  Let |arguments| be the list of arguments passed to this function.
    1.  Let |name| be the function name.
    1.  If |O| [=is a platform object=],
        then [=perform a security check=], passing:
        *   the platform object |O|,
        *   an identifier equal to |name|, and
        *   the type "<code>method</code>".
    1.  If |O| does not [=implement=] <var ignore>A</var>, then [=ECMAScript/throw=] a {{ECMAScript/TypeError}}.
    1.  Let |map| be the {{ECMAScript/Map}} object that is the value of |O|’s \[[BackingMap]] [=internal slot=].
    1.  Let |function| be [=?=] <a abstract-op>GetMethod</a>(|map|, |name|).
    1.  If |function| is <emu-val>undefined</emu-val>, then [=ECMAScript/throw=] a {{ECMAScript/TypeError}}.
    1.  Return [=?=] <a abstract-op>Call</a>(|function|, |map|, |arguments|).
</div>


<h5 id="es-map-size">size</h5>

There must exist a <code class="idl">size</code> property on
|A|’s [=interface prototype object=]
with the following characteristics:

*   The property has attributes
    { \[[Get]]: |G|, \[[Enumerable]]: <emu-val>false</emu-val>, \[[Configurable]]: <emu-val>true</emu-val> },
    where |G| is the interface’s <dfn id="dfn-map-size-getter" export>map size getter</dfn>,
    defined below.
*   <div algorithm="to invoke the size method of Maps">

        The [=map size getter=] is a [=built-in function object=]
        whose behavior when invoked is as follows:

        1.  Let |O| be the <emu-val>this</emu-val> value.
        1.  If |O| [=is a platform object=],
            then [=perform a security check=], passing:
            *   the platform object |O|,
            *   the identifier "<code>size</code>", and
            *   the type "<code>getter</code>".
        1.  If |O| does not [=implement=] <var ignore>A</var>, then [=ECMAScript/throw=] a {{ECMAScript/TypeError}}.
        1.  Let |map| be the {{ECMAScript/Map}} object that is the value of |O|’s \[[BackingMap]] [=internal slot=].
        1.  Return <a abstract-op>Get</a>(|map|, "<code>size</code>").
    </div>

    The value of the [=function object=]’s <code class="idl">length</code> property is the Number value <emu-val>0</emu-val>.

    The value of the [=function object=]’s <code class="idl">name</code> property is the String value "<code>size</code>".


<h5 id="es-map-entries">entries</h5>

An <code class="idl">entries</code> data property must exist on
|A|’s [=interface prototype object=]
with attributes { \[[Writable]]: <emu-val>true</emu-val>, \[[Enumerable]]: <emu-val>false</emu-val>, \[[Configurable]]: <emu-val>true</emu-val> }
and whose value is the [=function object=] that is the value of
the {{@@iterator}} property.


<h5 id="es-map-keys-values">keys and values</h5>

For both of <code class="idl">keys</code> and <code class="idl">values</code>, there must exist a data property with that name on
|A|’s [=interface prototype object=]
with the following characteristics:

*   The property has attributes { \[[Writable]]: <emu-val>true</emu-val>, \[[Enumerable]]: <emu-val>false</emu-val>, \[[Configurable]]: <emu-val>true</emu-val> }.
*   The value of the property is a [=built-in function object=] that [=forwards to the internal map object|forwards that name to the internal map object=].

The value of the [=function objects=]’ <code class="idl">length</code> properties is the Number value <emu-val>0</emu-val>.

The value of the [=function object=]’s <code class="idl">name</code> property is the String value "<code>keys</code>" or "<code>values</code>", correspondingly.


<h5 id="es-map-get-has">get and has</h5>

For both of <code class="idl">get</code> and <code class="idl">has</code>, there must exist a data property with that name on
|A|’s [=interface prototype object=] with the following characteristics:

*   The property has attributes
    { \[[Writable]]: <emu-val>true</emu-val>, \[[Enumerable]]: <emu-val>false</emu-val>, \[[Configurable]]: <emu-val>true</emu-val> }.
*   <div algorithm="to invoke the get and has methods of Maps">

        The value of the property is a [=built-in function object=]
        that behaves as follows when invoked:

        1.  Let |O| be the <emu-val>this</emu-val> value.
        1.  Let |name| be the name of the property – "<code>get</code>" or "<code>has</code>".
        1.  If |O| [=is a platform object=],
            then [=perform a security check=], passing:
            *   the platform object |O|,
            *   an identifier equal to |name|, and
            *   the type "<code>method</code>".
        1.  If |O| does not [=implement=] <var ignore>A</var>, then [=ECMAScript/throw=] a {{ECMAScript/TypeError}}.
        1.  Let |map| be the {{ECMAScript/Map}} object that is the value of |O|’s \[[BackingMap]] [=internal slot=].
        1.  Let |keyType| be the key type specified in the [=maplike declaration=].
        1.  Let |function| be [=!=] <a abstract-op>Get</a>(|map|, |name|).
        1.  Let |keyArg| be the first argument passed to this function, or <emu-val>undefined</emu-val> if not supplied.
        1.  Let |keyIDL| be the result of [=converted to an IDL value|converting=] |keyArg| to an IDL value of type |keyType|.
        1.  Let |key| be the result of [=converted to ECMAScript values|converting=] |keyIDL| to an ECMAScript value.
        1.  Return [=?=] <a abstract-op>Call</a>(|function|, |map|, «|key|»).
    </div>

The value of the [=function object=]’s <code class="idl">length</code> properties is the Number value <emu-val>1</emu-val>.

The value of the [=function object=]’s <code class="idl">name</code> property is the String value "<code>get</code>" or "<code>has</code>", correspondingly.


<h5 id="es-map-clear">clear</h5>

If |A| does not declare a [=member=]
with identifier "<code>clear</code>", and
|A| was declared with a read–write maplike declaration,
then a <code class="idl">clear</code> data property with the following characteristics
must exist on |A|’s
[=interface prototype object=]:

*   The property has attributes { \[[Writable]]: <emu-val>true</emu-val>, \[[Enumerable]]: <emu-val>false</emu-val>, \[[Configurable]]: <emu-val>true</emu-val> }.
*   The value of the property is a [=built-in function object=] that <a lt="forwards to the internal map object">forwards <code class="idl">clear</code> to the internal map object</a>.

The value of the [=function object=]’s <code class="idl">length</code> property is the Number value <emu-val>0</emu-val>.

The value of the [=function object=]’s <code class="idl">name</code> property is the String value "<code>clear</code>".


<h5 id="es-map-delete">delete</h5>

If |A| does not declare a [=member=]
with identifier "<code>delete</code>", and
|A| was declared with a read–write maplike declaration,
then a <code class="idl">delete</code> data property with the following characteristics
must exist on |A|’s
[=interface prototype object=]:

*   The property has attributes { \[[Writable]]: <emu-val>true</emu-val>, \[[Enumerable]]: <emu-val>false</emu-val>, \[[Configurable]]: <emu-val>true</emu-val> }.
*   <div algorithm="to invoke the delete method of Maps">

        The value of the property is a [=built-in function object=] that behaves as follows when invoked:

        1.  Let |O| be the <emu-val>this</emu-val> value.
        1.  If |O| [=is a platform object=],
            then [=perform a security check=], passing:
            *   the platform object |O|,
            *   the identifier "<code>delete</code>", and
            *   the type "<code>method</code>".
        1.  If |O| does not [=implement=] <var ignore>A</var>, then [=ECMAScript/throw=] a {{ECMAScript/TypeError}}.
        1.  Let |map| be the {{ECMAScript/Map}} object that is the value of |O|’s \[[BackingMap]] [=internal slot=].
        1.  Let |keyType| be the key type specified in the [=maplike declaration=].
        1.  Let |function| be [=!=] <a abstract-op>Get</a>(|map|, "<code>delete</code>").
        1.  Let |keyArg| be the first argument passed to this function, or <emu-val>undefined</emu-val> if not supplied.
        1.  Let |keyIDL| be the result of [=converted to an IDL value|converting=] |keyArg| to an IDL value of type |keyType|.
        1.  Let |key| be the result of [=converted to ECMAScript values|converting=] |keyIDL| to an ECMAScript value.
        1.  Return [=?=] <a abstract-op>Call</a>(|function|, |map|, «|key|»).
    </div>

The value of the [=function object=]’s <code class="idl">length</code> property is the Number value <emu-val>1</emu-val>.

The value of the [=function object=]’s <code class="idl">name</code> property is the String value "<code>delete</code>".


<h5 id="es-map-set">set</h5>

If |A| does not declare a [=member=] with identifier "<code>set</code>",
and |A| was declared with a read–write maplike declaration,
then a <code class="idl">set</code> data property with the following characteristics
must exist on |A|’s [=interface prototype object=]:

*   The property has attributes
    { \[[Writable]]: <emu-val>true</emu-val>, \[[Enumerable]]: <emu-val>false</emu-val>, \[[Configurable]]: <emu-val>true</emu-val> }.
*   <div algorithm="to invoke the set method of Maps">

        The value of the property is a [=built-in function object=] that behaves as follows when invoked:

        1.  Let |O| be the <emu-val>this</emu-val> value.
        1.  If |O| [=is a platform object=],
            then [=perform a security check=], passing:
            *   the platform object |O|,
            *   the identifier "<code>set</code>", and
            *   the type "<code>method</code>".
        1.  If |O| does not [=implement=] <var ignore>A</var>, then [=ECMAScript/throw=] a {{ECMAScript/TypeError}}.
        1.  Let |map| be the {{ECMAScript/Map}} object that is the value of |O|’s \[[BackingMap]] [=internal slot=].
        1.  Let |keyType| and |valueType| be the key and value types specified in the [=maplike declaration=].
        1.  Let |function| be [=!=] <a abstract-op>Get</a>(|map|, "<code>set</code>").
        1.  Let |keyArg| be the first argument passed to this function, or <emu-val>undefined</emu-val> if not supplied.
        1.  Let |valueArg| be the second argument passed to this function, or <emu-val>undefined</emu-val> if not supplied.
        1.  Let |keyIDL| be the result of [=converted to an IDL value|converting=] |keyArg| to an IDL value of type |keyType|.
        1.  Let |valueIDL| be the result of [=converted to an IDL value|converting=] |valueArg| to an IDL value of type |valueType|.
        1.  Let |key| be the result of [=converted to ECMAScript values|converting=] |keyIDL| to an ECMAScript value.
        1.  Let |value| be the result of [=converted to ECMAScript values|converting=] |valueIDL| to an ECMAScript value.
        1.  Perform [=?=] <a abstract-op>Call</a>(|function|, |map|, «|key|, |value|»).
        1.  Return |O|.
    </div>

The value of the [=function object=]’s <code class="idl">length</code> property is the Number value <emu-val>2</emu-val>.

The value of the [=function object=]’s <code class="idl">name</code> property is the String value "<code>set</code>".


<h4 id="es-setlike">Setlike declarations</h4>

Any object that [=implements=] an [=interface=]
that has a [=setlike declaration=]
must have a \[[BackingSet]] [=internal slot=], which is
initially set to a newly created {{ECMAScript/Set}} object.
This {{ECMAScript/Set}} object’s \[[SetData]] internal slot is
the object’s [=set entries=].

If an [=interface=] |A| is declared with a [=setlike declaration=], then
there exists a number of additional properties
on |A|’s [=interface prototype object=].
These additional properties are described in the sub-sections below.

<div algorithm>

    Some of the properties below are defined to have a [=built-in function object=] value that
    <dfn id="dfn-forwards-to-the-internal-set-object" export>forwards to the internal set object</dfn>
    for a given function name. Such functions behave as follows when invoked:

    1.  Let |O| be the <emu-val>this</emu-val> value.
    1.  Let |arguments| be the list of arguments passed to this function.
    1.  Let |name| be the function name.
    1.  If |O| [=is a platform object=],
        then [=perform a security check=], passing:
        *   the platform object |O|,
        *   an identifier equal to |name|, and
        *   the type "<code>method</code>".
    1.  If |O| does not [=implement=] <var ignore>A</var>,
        then [=ECMAScript/throw=] a {{ECMAScript/TypeError}}.
    1.  Let |set| be the {{ECMAScript/Set}} object that is
        the value of |O|’s \[[BackingSet]] [=internal slot=].
    1.  Let |function| be [=?=] <a abstract-op>GetMethod</a>(|set|, |name|).
    1.  If |function| is <emu-val>undefined</emu-val>,
        then [=ECMAScript/throw=] a {{ECMAScript/TypeError}}.
    1.  Return [=?=] <a abstract-op>Call</a>(|function|, |set|, |arguments|).
</div>


<h5 id="es-set-size">size</h5>

A <code class="idl">size</code> property must exist on |A|’s [=interface prototype object=]
with the following characteristics:

*   The property has attributes { \[[Get]]: |G|, \[[Enumerable]]: <emu-val>false</emu-val>, \[[Configurable]]: <emu-val>true</emu-val> },
    where |G| is the interface’s <dfn id="dfn-set-size-getter" export>set size getter</dfn>,
    defined below.
*   <div algorithm="to invoke the size method of Sets">

        The [=set size getter=] is a [=built-in function object=]
        whose behavior when invoked is as follows:

        1.  Let |O| be the <emu-val>this</emu-val> value.
        1.  If |O| [=is a platform object=],
            then [=perform a security check=], passing:
            *   the platform object |O|,
            *   the identifier "<code>size</code>", and
            *   the type "<code>getter</code>".
        1.  If |O| does not [=implement=] <var ignore>A</var>, then [=ECMAScript/throw=] a {{ECMAScript/TypeError}}.
        1.  Let |set| be the {{ECMAScript/Set}} object that is the value of |O|’s \[[BackingSet]] [=internal slot=].
        1.  Return the result of calling the \[[Get]] internal method of |set| passing "<code>size</code>" and |set| as arguments.
    </div>

    The value of the [=function object=]’s <code class="idl">length</code> property is the Number value <emu-val>0</emu-val>.

    The value of the [=function object=]’s <code class="idl">name</code> property is the String value "<code>size</code>".


<h5 id="es-set-values">values</h5>

A <code class="idl">values</code> data property must exist on |A|’s [=interface prototype object=]
with attributes { \[[Writable]]: <emu-val>true</emu-val>, \[[Enumerable]]: <emu-val>false</emu-val>, \[[Configurable]]: <emu-val>true</emu-val> }
and whose value is the [=function object=] that is the value of
the {{@@iterator}} property.


<h5 id="es-set-entries-keys">entries and keys</h5>

For both of <code class="idl">entries</code> and <code class="idl">keys</code>, there must exist a data property with that name on
|A|’s [=interface prototype object=] with the following characteristics:

*   The property has attributes
    { \[[Writable]]: <emu-val>true</emu-val>, \[[Enumerable]]: <emu-val>false</emu-val>, \[[Configurable]]: <emu-val>true</emu-val> }.
*   The value of the property is a [=built-in function object=] that
    [=forwards to the internal set object|forwards that name to the internal set object=].

The value of the [=function object=]’s <code class="idl">length</code> properties is
the Number value <emu-val>0</emu-val>.

The value of the [=function object=]’s <code class="idl">name</code> property is
the String value "<code>entries</code>" or "<code>keys</code>", correspondingly.


<h5 id="es-set-has">has</h5>

There must exist a <code class="idl">has</code> data property on |A|’s [=interface prototype object=]
with the following characteristics:

*   The property has attributes
    { \[[Writable]]: <emu-val>true</emu-val>, \[[Enumerable]]: <emu-val>false</emu-val>, \[[Configurable]]: <emu-val>true</emu-val> }.
*   <div algorithm="to invoke the has method of Sets">

        The value of the property is a [=built-in function object=] that behaves as follows when invoked:

        1.  Let |O| be the <emu-val>this</emu-val> value.
        1.  If |O| [=is a platform object=],
            then [=perform a security check=], passing:
            *   the platform object |O|,
            *   the identifier "<code>has</code>", and
            *   the type "<code>method</code>".
        1.  If |O| does not [=implement=] <var ignore>A</var>, then [=ECMAScript/throw=] a {{ECMAScript/TypeError}}.
        1.  Let |set| be the {{ECMAScript/Set}} object that is the value of |O|’s \[[BackingSet]] [=internal slot=].
        1.  Let |type| be the value type specified in the [=setlike declaration=].
        1.  Let |function| be [=!=] <a abstract-op>Get</a>(|set|, "<code>has</code>").
        1.  Let |arg| be the first argument passed to this function, or <emu-val>undefined</emu-val> if not supplied.
        1.  Let |idlValue| be the result of [=converted to an IDL value|converting=] |arg| to an IDL value of type |type|.
        1.  Let |value| be the result of [=converted to ECMAScript values|converting=] |idlValue| to an ECMAScript value.
        1.  Return [=?=] <a abstract-op>Call</a>(|function|, |set|, «|value|»).
    </div>

The value of the [=function object=]’s <code class="idl">length</code> property is a Number value <emu-val>1</emu-val>.

The value of the [=function object=]’s <code class="idl">name</code> property is the String value "<code>has</code>".


<h5 id="es-add-delete">add and delete</h5>

For both of <code class="idl">add</code> and <code class="idl">delete</code>, if:

*   |A| does not declare an [=member=] with a matching identifier, and
*   |A| was declared with a read–write setlike declaration,

then a data property with that name and the following characteristics
must exist on |A|’s [=interface prototype object=]:

*   The property has attributes { \[[Writable]]: <emu-val>true</emu-val>, \[[Enumerable]]: <emu-val>false</emu-val>, \[[Configurable]]: <emu-val>true</emu-val> }.
*   <div algorithm="to invoke the add and delete methods of Sets">

        The value of the property is a [=built-in function object=] that behaves as follows when invoked:

        1.  Let |O| be the <emu-val>this</emu-val> value.
        1.  Let |name| be the name of the property – "<code>add</code>" or "<code>delete</code>".
        1.  If |O| [=is a platform object=],
            then [=perform a security check=], passing:
            *   the platform object |O|,
            *   an identifier equal to |name|, and
            *   the type "<code>method</code>".
        1.  If |O| does not [=implement=] <var ignore>A</var>, then [=ECMAScript/throw=] a {{ECMAScript/TypeError}}.
        1.  Let |set| be the {{ECMAScript/Set}} object that is the value of |O|’s \[[BackingSet]] [=internal slot=].
        1.  Let |type| be the value type specified in the [=setlike declaration=].
        1.  Let |function| be [=?=] <a abstract-op>Get</a>(|set|, |name|).
        1.  Let |arg| be the first argument passed to this function, or <emu-val>undefined</emu-val> if not supplied.
        1.  Let |idlValue| be the result of [=converted to an IDL value|converting=] |arg| to an IDL value of type |type|.
        1.  Let |value| be the result of [=converted to ECMAScript values|converting=] |idlValue| to an ECMAScript value.
        1.  Let |result| be [=?=] <a abstract-op>Call</a>(|function|, |set|, «|value|»).
        1.  If |name| is "delete", then return |result|.
        1.  Otherwise, return |O|.
    </div>

The value of the [=function object=]’s <code class="idl">length</code> property is the Number value <emu-val>1</emu-val>.

The value of the [=function object=]’s <code class="idl">name</code> property is the String value "<code>add</code>" or "<code>delete</code>", correspondingly.


<h5 id="es-set-clear">clear</h5>

If |A| does not declare a [=member=]
with a matching identifier, and
|A| was declared with a read–write setlike declaration,
then a <code class="idl">clear</code> data property with the following characteristics
must exist on |A|’s
[=interface prototype object=]:

*   The property has attributes { \[[Writable]]: <emu-val>true</emu-val>, \[[Enumerable]]: <emu-val>false</emu-val>, \[[Configurable]]: <emu-val>true</emu-val> }.
*   The value of the property is a [=built-in function object=] that <a lt="forwards to the internal set object">forwards <code class="idl">clear</code> to the internal map object</a>.

The value of the [=function object=]’s <code class="idl">length</code> property is the Number value <emu-val>0</emu-val>.

The value of the [=function object=]’s <code class="idl">name</code> property is the String value "<code>clear</code>".


<h3 id="es-platform-objects">Platform objects implementing interfaces</h3>

<div algorithm>
    An ECMAScript value |value| <dfn>is a platform object</dfn> if [$Type$](|value|) is Object and
    if |value| has a \[[PrimaryInterface]] internal slot.
</div>

<div algorithm>
    An ECMAScript value |value| <dfn export>implements</dfn> an [=interface=] |interface|
    if |value| [=is a platform object=] and the [=inclusive inherited interfaces=] of
    |value|.\[[PrimaryInterface]] [=list/contains=] |interface|.

    Specifications may reference the concept "|object| implements |interface|"
    in various ways, including "|object| is an |interface| object".
</div>

Every [=platform object=] is associated with a [=Realm=], just
as the [=initial objects=] are.
This Realm is stored in the [=platform object=]'s \[[Realm]] slot.
It is the responsibility of specifications using Web IDL to state
which Realm (or, by proxy, which global object) each platform
object is associated with.
In particular, the algorithms below associate the new [=platform object=] with
the Realm given as an argument.

<div algorithm>
  To <dfn export lt=new>create a new object implementing the interface</dfn> |interface|, with a
  Realm |realm|, perform the following steps:

    1.  Return the result of [=internally create a new object implementing the
        interface|internally creating a new object implementing=] |interface|, with |realm| and
        <emu-val>undefined</emu-val>.
</div>

<div algorithm>
  To <dfn>internally create a new object implementing the interface</dfn> |interface|, with a
  Realm |realm| and a JavaScript value |newTarget|, perform the following steps:

    1.  Assert: |interface| is [=exposed=] in |realm|.
    1.  If |newTarget| is <emu-val>undefined</emu-val>, then:
        1.  Let |prototype| be the [=interface prototype object=] for |interface| in
            |realm|.
    1.  Otherwise:
        1.  Assert: [$IsCallable$](|newTarget|) is true.
        1.  Let |prototype| be [=?=] [$Get$](|newTarget|, "prototype").
        1.  If [$Type$](|prototype|) is not Object, then:
            1.  Let |targetRealm| be [$GetFunctionRealm$](|newTarget|).
            1.  Set |prototype| to the [=interface prototype object=] for |interface| in
                |targetRealm|.
    1.  Let |slots| be « \[[Realm]], \[[PrimaryInterface]] ».
    1.  Let |instance| be a newly created [=ECMAScript/object=] in |realm|
        with an internal slot for each name in |slots|.
    1.  Set |instance|.\[[Realm]] to |realm|.
    1.  Set |instance|.\[[PrimaryInterface]] to |interface|.
    1.  Set |instance|.\[[Prototype]] to |prototype|.
    1.  Set |instance|'s essential internal methods to the definitions specified in
        [=ECMA-262 Ordinary object internal methods and internal slots=].
    1.  Let |interfaces| be the [=inclusive inherited interfaces=] of |interface|.
    1.  [=list/iterate|For every=] [=interface=] |ancestor interface| in |interfaces|:
        1.  Let |unforgeables| be the value of the \[[Unforgeables]] slot of the [=interface
            object=] of |ancestor interface| in |realm|.
        1.  Let |keys| be [=!=] |unforgeables|.\[[OwnPropertyKeys]]().
        1.  [=list|For each=] element |key| of |keys|:
            1.  Let |descriptor| be [=!=] |unforgeables|.\[[GetOwnProperty]](|key|).
            1.  Perform [=!=] [$DefinePropertyOrThrow$](|instance|, |key|, |descriptor|).
    1.  If |interface| is declared with the [{{Global}}] [=extended attribute=], then:
        1.  [=Define the regular operations=] of |interface| on |instance|, given |realm|.
        1.  [=Define the regular attributes=] of |interface| on |instance|, given |realm|.
        1.  [=Define the global property references=] on |instance|, given |realm|.
        1.  Set |instance|.\[[SetPrototypeOf]] as defined in [[#platform-object-setprototypeof]].
    1.  Otherwise, if |interfaces| contains an [=interface=] which
        [=support indexed properties|supports indexed properties=],
        [=support named properties|named properties=], or both:
        1.  Set |instance|.\[[GetOwnProperty]] as defined in
            [[#legacy-platform-object-getownproperty]].
        1.  Set |instance|.\[[Set]] as defined in
            [[#legacy-platform-object-set]].
        1.  Set |instance|.\[[DefineOwnProperty]] as defined in
            [[#legacy-platform-object-defineownproperty]].
        1.  Set |instance|.\[[Delete]] as defined in
            [[#legacy-platform-object-delete]].
        1.  Set |instance|.\[[PreventExtensions]] as defined in
            [[#legacy-platform-object-preventextensions]].
        1.  Set |instance|.\[[OwnPropertyKeys]] as defined in
            [[#legacy-platform-object-ownpropertykeys]].
    1.  Return |instance|.
</div>

<div algorithm>
  To <dfn>define the global property references</dfn> on |target|, given [=Realm=] |realm|,
  perform the following steps:

    1.  Let |interfaces| be a [=list=] that contains every [=interface=] that is [=exposed=] in
        |realm|.
    1.  Sort |interfaces| in such a way that if |A| and |B| are [=list/items=] of |interfaces|,
        and |A| [=interface/inherits=] from |B|, |A| has a higher index in |interfaces| than |B|.
    1.  [=list/iterate|For every=] |interface| of |interfaces|:
        1.  If |interface| is not declared with the [{{NoInterfaceObject}}] or
            [{{LegacyNamespace}}] [=extended attributes=], then:
            1.  Let |id| be |interface|'s [=identifier=].
            1.  Let |interfaceObject| be the result of [=create an interface object|creating
                an interface object=] for |interface| with |id| in |realm|.
            1.  Perform [=!=] [$CreateMethodProperty$](|target|, |id|, |interfaceObject|).
            1.  If the |interface| is declared with a [{{LegacyWindowAlias}}] [=extended attribute=],
                and |target| implements the {{Window}} [=interface=], then:
                1.  [=list/iterate|For every=] [=LegacyWindowAlias identifier|identifier=] |id| in
                    [{{LegacyWindowAlias}}]'s [=LegacyWindowAlias identifier|identifiers=]:
                    1.  Perform [=!=] [$CreateMethodProperty$](|target|, |id|, |interfaceObject|).
        1.  If the |interface| is declared with a [{{NamedConstructor}}] [=extended attribute=],
            then:
            1.  [=list/iterate|For every=] [=NamedConstructor identifier|identifier=] |id| in
                [{{NamedConstructor}}]'s [=NamedConstructor identifier|identifiers=]:
                1.  Let |namedConstructor| be the result of [=create a named constructor|creating
                    a named constructor=] with |id| for |interface| in |realm|.
                1.  Perform [=!=] [$CreateMethodProperty$](|target|, |id|, |namedConstructor|).
    1.  [=list/iterate|For every=] [=callback interface=] |interface| that is [=exposed=] in
        |realm| and on which [=constants=] are defined:
        1.  Let |id| be |interface|'s [=identifier=].
        1.  Let |interfaceObject| be the result of [=create a legacy callback interface
            object|creating a legacy callback interface object=] for |interface| with |id| in |realm|.
        1.  Perform [=!=] [$CreateMethodProperty$](|target|, |id|, |interfaceObject|).
    1.  [=list/iterate|For every=] [=namespace=] |namespace| that is [=exposed=] in
        |realm|:
        1.  Let |id| be |namespace|'s [=identifier=].
        1.  Let |namespaceObject| be the result of [=create a namespace object|creating a namespace object=] for |namespace| in |realm|.
        1.  Perform [=!=] [$CreateMethodProperty$](|target|, |id|, |namespaceObject|).
</div>

<div class="note">
  The set of interfaces that a [=platform object=] [=implements=] does not change over
  the lifetime of the object.

  Multiple [=platform objects=] with different [=Realm/global objects=] will share
  a reference to the same [=interface=] in their \[[PrimaryInterface]] internal
  slots. For example, a page may contain a same-origin iframe, with the iframe's
  method being called on the main page's element of the same kind, with no exception
  thrown.

  [=Interface mixins=] do not participate directly in the evaluation of the [=implements=]
  algorithm. Instead, each [=interface=] that the [=interface mixin=] is [=included=] in
  has its own "copy" of each [=member=] of the [=interface mixin=], and the corresponding
  [=creating an operation function|operation function=] checks that the receiver [=implements=]
  the particular [=interface=] which [=includes=] the [=interface mixin=].
</div>

<div algorithm>
  The <dfn id="dfn-primary-interface" export>primary interface</dfn> of a [=platform object=] is
  the value of the object's \[[PrimaryInterface]] internal slot, which is is the most-derived
  [=interface=] that it [=implements=].
</div>

The [=Realm=] that a given [=platform object=]
is associated with can <dfn id="dfn-change-global-environment" for="Realm" export>change</dfn> after it has been created.  When
the [=Realm=] associated with a platform object is changed, its
\[[Prototype]] [=internal slot=] must be immediately
updated to be the [=interface prototype object=]
of the [=primary interface=]
from the [=platform object=]’s newly associated [=Realm=].

The [=class string=] of
a platform object that implements one or more interfaces
must be the [=qualified name=] of
the [=primary interface=]
of the platform object.

Additionally, [=platform objects=] which implement an [=interface=]
which has a [{{Global}}] [=extended attribute=]
get properties declaratively from:

* [[#es-stringifier]],
* [[#es-iterators]],
* [[#es-iterable]],
* [[#es-maplike]], and
* [[#es-setlike]].

Issue: Define those properties imperatively instead.

<h4 id="platform-object-setprototypeof" oldids="platformobjectsetprototypeof">\[[SetPrototypeOf]]</h4>

<div algorithm="to invoke the internal [[SetPrototypeOf]] method of a platform object that implements an interface with [Global] extended attribute">

    When the \[[SetPrototypeOf]] internal method of a [=platform object=] |O| that implements an
    [=interface=] with the [{{Global}}] [=extended attribute=] is called with
    ECMAScript language value |V|, the following step is taken:

    1.  Return [=?=] <a abstract-op>SetImmutablePrototype</a>(|O|, |V|).

</div>

Note: For {{Window}} objects, it is unobservable whether this is implemented, since the presence of
the {{WindowProxy}} object ensures that \[[SetPrototypeOf]] is never called on a {{Window}} object
directly. For other global objects, however, this is necessary.


<h3 id="es-legacy-platform-objects" oldids="indexed-and-named-properties">Legacy platform objects</h3>

[=Legacy platform objects=] will appear to have additional properties that correspond to their
[=indexed properties|indexed=] and [=named properties=].  These properties are not “real” own
properties on the object, but are made to look like they are by being exposed
by the <a href="#legacy-platform-object-getownproperty">\[[GetOwnProperty]] internal method</a> .

It is permissible for an object to implement multiple interfaces that support indexed properties.
However, if so, and there are conflicting definitions as to the object’s
[=supported property indices=],
then it is undefined what additional properties the object will appear to
have, or what its exact behavior will be with regard to its indexed properties.
The same applies for named properties.

The [=indexed property getter=]
that is defined on the derived-most interface that the
legacy platform object implements is the one that defines the behavior
when indexing the object with an [=array index=].  Similarly for
[=indexed property setters=].
This way, the definitions of these special operations from
ancestor interfaces can be overridden.

A property name is an <dfn id="dfn-unforgeable-property-name" export>unforgeable property name</dfn> on a
given platform object |O| if the object implements an [=interface=] that
has an [=interface member=] with that identifier
and that interface member is [=unforgeable=] on any of
the interfaces that |O| implements.

Support for [=getters=] is handled in [[#legacy-platform-object-getownproperty]],
and for [=setters=] in [[#legacy-platform-object-defineownproperty]]
and [[#legacy-platform-object-set]].

Additionally, [=legacy platform objects=] have internal methods as defined in:

* [[#legacy-platform-object-delete]],
* [[#legacy-platform-object-preventextensions]], and
* [[#legacy-platform-object-ownpropertykeys]].


<h4 id="legacy-platform-object-getownproperty" dfn oldids="getownproperty" lt=GetOwnProperty for="legacy platform object">\[[GetOwnProperty]]</h4>

<div algorithm="to invoke the [[GetOwnProperty]] internal method of legacy platform objects">

    The \[[GetOwnProperty]] internal method of every [=legacy platform object=] |O|
    must behave as follows when called with property name |P|:

    1. Return <a abstract-op>LegacyPlatformObjectGetOwnProperty</a>(|O|, |P|, <emu-val>false</emu-val>).
</div>


<h4 id="legacy-platform-object-set" oldids="platformobjectset">\[[Set]]</h4>

<div algorithm="to invoke the [[Set]] internal method of legacy platform objects">

    The \[[Set]] internal method of every [=legacy platform object=] |O|
    must behave as follows when called with
    property name |P|, value |V|, and ECMAScript language value |Receiver|:

    1.  If |O| and |Receiver| are the same object, then:
        1.  If |O| [=implements=] an interface with an [=indexed property setter=]
            and |P| [=is an array index=], then:
            1.  [=Invoke the indexed property setter=] with |P| and |V|.
            1.  Return <emu-val>true</emu-val>.
        1.  If |O| [=implements=] an interface with a [=named property setter=]
            and <a abstract-op>Type</a>(|P|) is String, then:
            1.  [=Invoke the named property setter=] with |P| and |V|.
            1.  Return <emu-val>true</emu-val>.
    1.  Let |ownDesc| be <a abstract-op>LegacyPlatformObjectGetOwnProperty</a>(|O|, |P|, <emu-val>true</emu-val>).
    1.  Perform [=?=] <a abstract-op>OrdinarySetWithOwnDescriptor</a>(|O|, |P|, |V|, |Receiver|, |ownDesc|).
</div>


<h4 id="legacy-platform-object-defineownproperty" oldids="defineownproperty">\[[DefineOwnProperty]]</h4>

<div algorithm="to invoke the [[DefineOwnProperty]] internal method of legacy platform objects">

    When the \[[DefineOwnProperty]] internal method of a [=legacy platform object=] |O|
    is called with property key |P| and [=Property Descriptor=] |Desc|,
    the following steps must be taken:

    1.  If |O| [=support indexed properties|supports indexed properties=] and
        |P| [=is an array index=], then:
        1.  If the result of calling <a abstract-op>IsDataDescriptor</a>(|Desc|) is
            <emu-val>false</emu-val>, then return
            <emu-val>false</emu-val>.
        1.  If |O| does not implement an interface with an
            [=indexed property setter=], then return <emu-val>false</emu-val>.
        1.  [=Invoke the indexed property setter=] with |P| and |Desc|.\[[Value]].
        1.  Return <emu-val>true</emu-val>.
    1.  If |O| [=support named properties|supports named properties=],
        |O| does not implement an [=interface=] with the [{{Global}}] [=extended attribute=],
        <a abstract-op>Type</a>(|P|) is String,
        and |P| is not an [=unforgeable property name=]
        of |O|, then:
        1.  Let |creating| be true if |P| is not a [=supported property name=], and false otherwise.
        1.  If |O| [=implements=] an interface with the [{{OverrideBuiltins}}]
            [=extended attribute=] or |O| does not have an own property
            named |P|, then:
            1.  If |creating| is false and |O| does not implement an
                interface with a [=named property setter=], then return <emu-val>false</emu-val>.
            1.  If |O| [=implements=] an interface with a
                [=named property setter=], then:
                1.  If the result of calling <a abstract-op>IsDataDescriptor</a>(|Desc|) is
                    <emu-val>false</emu-val>, then return
                    <emu-val>false</emu-val>.
                1.  [=Invoke the named property setter=] with |P| and |Desc|.\[[Value]].
                1.  Return <emu-val>true</emu-val>.
    1.  If |O| does not implement an [=interface=] with the [{{Global}}] [=extended attribute=],
        then set |Desc|.\[[Configurable]] to <emu-val>true</emu-val>.
    1.  Return <a abstract-op>OrdinaryDefineOwnProperty</a>(|O|, |P|, |Desc|).
</div>


<h4 id="legacy-platform-object-delete" oldids="delete">\[[Delete]]</h4>

<div algorithm="to invoke the [[Delete]] internal method of legacy platform objects">

    The \[[Delete]] internal method of every [=legacy platform object=] |O|
    must behave as follows when called with property name |P|.

    1.  If |O| [=support indexed properties|supports indexed properties=] and
        |P| [=is an array index=], then:
        1.  Let |index| be the result of calling <a abstract-op>ToUint32</a>(|P|).
        1.  If |index| is not a [=supported property indices|supported property index=], then return <emu-val>true</emu-val>.
        1.  Return <emu-val>false</emu-val>.
    1.  If |O| [=support named properties|supports named properties=],
        |O| does not implement an [=interface=] with the [{{Global}}] [=extended attribute=]
        and the result of calling the [=named property visibility algorithm=]
        with property name |P| and object |O| is true, then:
        1.  If |O| does not implement an interface with a [=named property deleter=], then return <emu-val>false</emu-val>.
        1.  Let |operation| be the operation used to declare the named property deleter.
        1.  If |operation| was defined without an [=identifier=], then:
            1.  Perform the steps listed in the interface description to
                [=delete an existing named property=]
                with |P| as the name.
            1.  If the steps indicated that the deletion failed, then return <emu-val>false</emu-val>.
        1.  Otherwise, |operation| was defined with an identifier:
            1.  Perform the steps listed in the description of |operation| with |P| as the only argument value.
            1.  If |operation| was declared with a [=return type=] of {{boolean}}
                and the steps returned <emu-val>false</emu-val>, then return <emu-val>false</emu-val>.
        1.  Return <emu-val>true</emu-val>.
    1.  If |O| has an own property with name |P|, then:
        1.  If the property is not configurable, then return <emu-val>false</emu-val>.
        1.  Otherwise, remove the property from |O|.
    1.  Return <emu-val>true</emu-val>.
</div>


<h4 id="legacy-platform-object-preventextensions" oldids="preventextensions">\[[PreventExtensions]]</h4>

<div algorithm="to invoke the internal [[PreventExtensions]] method of legacy platform objects">

    When the \[[PreventExtensions]] internal method of a [=legacy platform object=] is called,
    the following steps are taken:

    1.  Return <emu-val>false</emu-val>.

    Note: this keeps [=legacy platform objects=] extensible by
    making \[[PreventExtensions]] fail for them.
</div>


<h4 id="legacy-platform-object-ownpropertykeys" oldids="property-enumeration,legacy-platform-object-property-enumeration">\[[OwnPropertyKeys]]</h4>

This document does not define a complete property enumeration order
for [=platform objects=] implementing [=interfaces=]
(or for <a href="#es-exception-objects">platform objects representing exceptions</a>).
However, it does for [=legacy platform objects=] by defining the \[[OwnPropertyKeys]]
internal method as follows.

<div algorithm="to invoke the internal [[OwnPropertyKeys]] method of legacy platform objects">

    When the \[[OwnPropertyKeys]] internal method of a [=legacy platform object=] |O| is called,
    the following steps are taken:

    1.  Let |keys| be a new empty [=list=] of ECMAScript String and Symbol values.
    1.  If |O| [=support indexed properties|supports indexed properties=], then [=list|for each=] |index| of |O|’s
        [=supported property indices=], in ascending numerical order, [=list|append=] [=!=] <a abstract-op>ToString</a>(|index|) to
        |keys|.
    1.  If |O| [=support named properties|supports named properties=], then [=list|for each=] |P| of |O|’s
        [=supported property names=] that is visible according to the [=named property visibility algorithm=],
        [=list|append=] |P| to |keys|.
    1.  [=list|For each=] |P| of |O|’s own property keys that is a String, in ascending chronological order of
        property creation, [=list|append=] |P| to |keys|.
    1.  [=list|For each=] |P| of |O|’s own property keys that is a Symbol, in ascending chronological order of
        property creation, [=list|append=] |P| to |keys|.
    1.  Assert: |keys| has no duplicate items.
    1.  Return |keys|.

</div>

<h4 id="legacy-platform-object-abstract-ops">Abstract operations</h4>

<div algorithm="to determine if a property name is an array index">

    To determine if a property name |P| <dfn lt="is an array index|is not an array index"
    oldids="dfn-array-index-property-name">is an [=array index=]</dfn>, the following algorithm is
    applied:

    1.  If <a abstract-op>Type</a>(|P|) is not String, then return <emu-val>false</emu-val>.
    1.  Let |index| be [=!=] <a abstract-op>CanonicalNumericIndexString</a>(|P|).
    1.  If |index| is <emu-val>undefined</emu-val>, then return <emu-val>false</emu-val>.
    1.  If <a abstract-op>IsInteger</a>(|index|) is <emu-val>false</emu-val>,
        then return <emu-val>false</emu-val>.
    1.  If |index| is −0, then return <emu-val>false</emu-val>.
    1.  If |index| &lt; 0, then return <emu-val>false</emu-val>.
    1.  If |index| ≥ 2<sup>32</sup> − 1, then return <emu-val>false</emu-val>.

        Note: 2<sup>32</sup> − 1 is the maximum array length allowed by ECMAScript.
    1.  Return <emu-val>true</emu-val>.

</div>

<div algorithm>

    The <dfn id="dfn-named-property-visibility" export>named property visibility algorithm</dfn>
    is used to determine if a given named property is exposed on an object.
    Some named properties are not exposed on an object depending on whether
    the [{{OverrideBuiltins}}] [=extended attribute=] was used.
    The algorithm operates as follows, with property name |P| and object |O|:

    1.  If |P| is not a [=supported property name=] of |O|, then return false.
    1.  If |O| has an own property named |P|, then return false.

          Note: This will include cases in which |O| has unforgeable properties,
          because in practice those are always set up before objects have any supported property names,
          and once set up will make the corresponding named properties invisible.

    1.  If |O| [=implements=] an interface that has the [{{OverrideBuiltins}}]
        [=extended attribute=], then return true.
    1.  Let |prototype| be |O|.\[[GetPrototypeOf]]().
    1.  While |prototype| is not null:
        1.  If |prototype| is not a [=named properties object=],
            and |prototype| has an own property named |P|, then return false.
        1.  Set |prototype| to |prototype|.\[[GetPrototypeOf]]().
    1.  Return true.
</div>

<div class="note">

    This should ensure that for objects with named properties, property resolution is done in the following order:

    1.  Indexed properties.
    1.  Own properties, including unforgeable attributes and operations.
    1.  Then, if [{{OverrideBuiltins}}]:
        1.  Named properties.
        1.  Properties from the prototype chain.
    1.  Otherwise, if not [{{OverrideBuiltins}}]:
        1.  Properties from the prototype chain.
        1.  Named properties.
</div>

<div algorithm>

    To <dfn id="invoke-indexed-setter" oldids="invoking-indexed-setter" export lt="invoke the indexed property setter">invoke an indexed property setter</dfn>
    with property name |P| and ECMAScript value |V|, the following steps must be performed:

    1.  Let |index| be the result of calling <a abstract-op>ToUint32</a>(|P|).
    1.  Let |creating| be true if |index| is not a [=supported property indices|supported property index=],
        and false otherwise.
    1.  Let |operation| be the operation used to declare the indexed property setter.
    1.  Let |T| be the type of the second argument of |operation|.
    1.  Let |value| be the result of [=converted to an IDL value|converting=] |V| to an IDL value of type |T|.
    1.  If |operation| was defined without an [=identifier=], then:
        1.  If |creating| is true, then perform the steps listed in the interface description to
            [=set the value of a new indexed property=]
            with |index| as the index and |value| as the value.
        1.  Otherwise, |creating| is false.  Perform the steps listed in the interface description to
            [=set the value of an existing indexed property=]
            with |index| as the index and |value| as the value.
    1.  Otherwise, |operation| was defined with an identifier.  Perform the steps listed in the description of
        |operation| with |index| and |value| as the two argument values.
</div>

<div algorithm>

    To <dfn id="invoke-named-setter" oldids="invoking-named-setter" export lt="invoke the named property setter">invoke a named property setter</dfn>
    with property name |P| and ECMAScript value |V|, the following steps must be performed:

    1.  Let |creating| be true if |P| is not a [=supported property name=], and false otherwise.
    1.  Let |operation| be the operation used to declare the named property setter.
    1.  Let |T| be the type of the second argument of |operation|.
    1.  Let |value| be the result of [=converted to an IDL value|converting=] |V| to an IDL value of type |T|.
    1.  If |operation| was defined without an [=identifier=], then:
        1.  If |creating| is true, then perform the steps listed in the interface description to
            [=set the value of a new named property=]
            with |P| as the name and |value| as the value.
        1.  Otherwise, |creating| is false.  Perform the steps listed in the interface description to
            [=set the value of an existing named property=]
            with |P| as the name and |value| as the value.
    1.  Otherwise, |operation| was defined with an identifier.  Perform the steps listed in the description of
        |operation| with |P| and |value| as the two argument values.
</div>

<div algorithm>

    The <dfn id="LegacyPlatformObjectGetOwnProperty" oldids="getownproperty-guts" abstract-op>LegacyPlatformObjectGetOwnProperty</dfn>
    abstract operation performs the following steps when called with
    an object |O|, a property name |P|, and a boolean |ignoreNamedProps| value:

    1.  If |O| [=support indexed properties|supports indexed properties=]
        and |P| [=is an array index=], then:
        1.  Let |index| be the result of calling <a abstract-op>ToUint32</a>(|P|).
        1.  If |index| is a [=supported property indices|supported property index=], then:
            1.  Let |operation| be the operation used to declare the indexed property getter.
            1.  Let |value| be an uninitialized variable.
            1.  If |operation| was defined without an [=identifier=], then
                set |value| to the result of performing the steps listed in the interface description to
                [=determine the value of an indexed property=]
                with |index| as the index.
            1.  Otherwise, |operation| was defined with an identifier.  Set |value| to the result
                of performing the steps listed in the description of |operation| with |index| as the only argument value.
            1.  Let |desc| be a newly created [=Property Descriptor=] with no fields.
            1.  Set |desc|.\[[Value]] to the result of [=converted to an ECMAScript value|converting=]
                |value| to an ECMAScript value.
            1.  If |O| [=implements=] an interface with an [=indexed property setter=], then set
                |desc|.\[[Writable]] to <emu-val>true</emu-val>, otherwise set it to
                <emu-val>false</emu-val>.
            1.  Set |desc|.\[[Enumerable]] and |desc|.\[[Configurable]] to <emu-val>true</emu-val>.
            1.  Return |desc|.
        1.  Set |ignoreNamedProps| to true.
    1.  If |O| [=support named properties|supports named properties=] and
        |ignoreNamedProps| is false, then:
        1.  If the result of running the [=named property visibility algorithm=] with
            property name |P| and object |O| is true, then:
            1.  Let |operation| be the operation used to declare the named property getter.
            1.  Let |value| be an uninitialized variable.
            1.  If |operation| was defined without an [=identifier=], then
                set |value| to the result of performing the steps listed in the interface description to
                [=determine the value of a named property=]
                with |P| as the name.
            1.  Otherwise, |operation| was defined with an identifier.  Set |value| to the result
                of performing the steps listed in the description of |operation| with |P| as the only argument value.
            1.  Let |desc| be a newly created [=Property Descriptor=] with no fields.
            1.  Set |desc|.\[[Value]] to the result of [=converted to an ECMAScript value|converting=]
                |value| to an ECMAScript value.
            1.  If |O| [=implements=] an interface with a [=named property setter=], then set
                |desc|.\[[Writable]] to <emu-val>true</emu-val>, otherwise set it to
                <emu-val>false</emu-val>.
            1.  If |O| [=implements=] an interface with the
                [{{LegacyUnenumerableNamedProperties}}]
                [=extended attribute=],
                then set |desc|.\[[Enumerable]] to <emu-val>false</emu-val>,
                otherwise set it to <emu-val>true</emu-val>.
            1.  Set |desc|.\[[Configurable]] to <emu-val>true</emu-val>.
            1.  Return |desc|.
    1.  Return <a abstract-op>OrdinaryGetOwnProperty</a>(|O|, |P|).
</div>

<h3 id="es-user-objects">Callback interfaces</h3>

As described in [[#idl-objects]],
[=callback interfaces=] can be
implemented in script by any ECMAScript object.
The following cases explain how a [=callback interface=]'s [=operation=] is invoked on a given
object:

*   If the object is [=ECMAScript/callable=], then the implementation of the operation is the
    callable object itself.
*   Otherwise, the implementation of the operation is calling the result of invoking the
    internal \[[Get]] method on the object with a property name that is the [=identifier=] of
    the operation.

Note that ECMAScript objects need not have
properties corresponding to [=constants=]
on them to be considered as
implementing [=callback interfaces=] that happen
to have constants declared on them.

A <dfn>Web IDL arguments list</dfn> is a [=list=] of values each of which is either an IDL value or
the special value “missing”, which represents a missing optional argument.

<div algorithm>
    To <dfn lt="converting" for="Web IDL arguments list">convert a Web IDL arguments list to an
    ECMAScript arguments list</dfn>, given a [=Web IDL arguments list=] |args|, perform the
    following steps:

    1.  Let |esArgs| be an empty [=list=].
    1.  Let |i| be 0.
    1.  Let |count| be 0.
    1.  While |i| &lt; |args|'s [=list/size=]:
        1.  If |args|[|i|] is the special value “missing”, then [=list/append=]
            <emu-val>undefined</emu-val> to |esArgs|.
        1.  Otherwise, |args|[|i|] is an IDL value:
            1.  Let |convertResult| be the result of [=converted to an ECMAScript value|converting=]
                |args|[|i|] to an ECMAScript value. Rethrow any exceptions.
            1.  [=list/Append=] |convertResult| to |esArgs|.
            1.  Set |count| to |i| + 1.
        1.  Set |i| to |i| + 1.
    1.  Truncate |esArgs| to contain |count| items.
    1.  Return |esArgs|.
</div>

<div algorithm="to call a user object's operation">

    To <dfn id="call-a-user-objects-operation" export>call a user object's operation</dfn>,
    given a [=callback interface type=] value |value|,
    operation name |opName|, [=Web IDL arguments list=] |args|, and optional
    <dfn id="dfn-callback-this-value" export>callback this value</dfn> |thisArg|,
    perform the following steps.
    These steps will either return an IDL value or throw an exception.

    1.  Let |completion| be an uninitialized variable.
    1.  If |thisArg| was not given, let |thisArg| be <emu-val>undefined</emu-val>.
    1.  Let |O| be the ECMAScript object corresponding to |value|.
    1.  Let |realm| be |O|'s [=associated Realm=].
    1.  Let |relevant settings| be |realm|'s [=Realm/settings object=].
    1.  Let |stored settings| be |value|'s [=callback context=].
    1.  [=Prepare to run script=] with |relevant settings|.
    1.  [=Prepare to run a callback=] with |stored settings|.
    1.  Let |X| be |O|.
    1.  If [=!=] <a abstract-op>IsCallable</a>(|O|) is false, then:
        1.  Let |getResult| be <a abstract-op>Get</a>(|O|, |opName|).
        1.  If |getResult| is an [=abrupt completion=], set |completion|
            to |getResult| and jump to the step labeled <a href="#call-user-object-operation-return"><i>return</i></a>.
        1.  Set |X| to |getResult|.\[[Value]].
        1.  If [=!=] <a abstract-op>IsCallable</a>(|X|) is <emu-val>false</emu-val>,
            then set |completion| to a new <a abstract-op>Completion</a>{\[[Type]]: throw, \[[Value]]: a
            newly created {{ECMAScript/TypeError}} object, \[[Target]]: empty}, and jump
            to the step labeled <a href="#call-user-object-operation-return"><i>return</i></a>.
        1.  Set |thisArg| to |O| (overriding the provided value).
    1.  Let |esArgs| be the result of [=Web IDL arguments list/converting=] |args| to an ECMAScript
        arguments list. If this throws an exception, set |completion| to the completion value
        representing the thrown exception and jump to the step labeled
        <a href="#call-user-object-operation-return"><i>return</i></a>.
    1.  Let |callResult| be <a abstract-op>Call</a>(|X|, |thisArg|, |esArgs|).
    1.  If |callResult| is an [=abrupt completion=], set |completion| to
        |callResult| and jump to the step labeled <a href="#call-user-object-operation-return"><i>return</i></a>.
    1.  Set |completion| to the result of [=converted to an IDL value|converting=]
        |callResult|.\[[Value]] to an IDL value of the same type as the operation’s
        return type.
    1.  <i id="call-user-object-operation-return">Return:</i> at this
        point |completion| will be set to an ECMAScript completion value.
        1.  [=Clean up after running a callback=] with |stored settings|.
        1.  [=Clean up after running script=] with |relevant settings|.
        1.  If |completion| is a normal completion, return |completion|.
        1.  If |completion| is an [=abrupt completion=] and the operation has a [=return type=]
            that is <em>not</em> a [=promise type=], return |completion|.
        1.  Let |rejectedPromise| be [=!=] <a abstract-op>Call</a>({{%Promise_reject%}},
            {{%Promise%}}, «|completion|.\[[Value]]»).
        1.  Return the result of [=converted to an IDL value|converting=]
            |rejectedPromise| to the operation's return type.
</div>


<h4 id="legacy-callback-interface-object">Legacy callback interface object</h4>

For every [=callback interface=] that is [=exposed=] in
a given [=Realm=]
and on which [=constants=] are defined,
a corresponding property exists on the [=Realm=]'s [=Realm/global object=].
The name of the property is the [=identifier=] of the [=callback interface=],
and its value is an object called the
<dfn id="dfn-legacy-callback-interface-object" export>legacy callback interface object</dfn>.

The [=legacy callback interface object=] for a given [=callback interface=]
is a [=built-in function object=].
It has properties that correspond to the [=constants=] defined on that interface,
as described in sections [[#es-constants]].

Note: Since a [=legacy callback interface object=] is a [=function object=]
the <code>typeof</code> operator will return "function"
when applied to a [=legacy callback interface object=].

<div algorithm>

    The [=legacy callback interface object=] for a given [=callback interface=] |interface|
    with [=identifier=] |id| and in [=Realm=] |realm|
    is <dfn lt="create a legacy callback interface object">created</dfn> as follows:

    1.  Let |steps| be the following steps:
        1.  [=ECMAScript/Throw=] a {{ECMAScript/TypeError}}.
    1.  Let |F| be [=!=] <a abstract-op>CreateBuiltinFunction</a>(|steps|, « », |realm|).
    1.  Perform [=!=] <a abstract-op>SetFunctionName</a>(|F|, |id|).
    1.  Perform [=!=] <a abstract-op>SetFunctionLength</a>(|F|, 0).
    1.  [=Define the constants=] of |interface| on |F| given |realm|.
    1.  Return |F|.
</div>


<h3 id="es-invoking-callback-functions">Invoking callback functions</h3>

An ECMAScript [=ECMAScript/callable=] object that is being
used as a [=callback function=] value is
called in a manner similar to how [=operations=]
on [=callback interface=] values are called (as
described in the previous section).

<div algorithm>

    To <dfn id="invoke-a-callback-function" export>invoke</dfn> a
    [=callback function type=] value |callable| with a [=Web IDL arguments list=] |args|
    and an optional [=callback this value|callback this value=] |thisArg|,
    perform the following steps.
    These steps will either return an IDL value or throw an exception.

    1.  Let |completion| be an uninitialized variable.
    1.  If |thisArg| was not given, let |thisArg| be <emu-val>undefined</emu-val>.
    1.  Let |F| be the ECMAScript object corresponding to |callable|.
    1.  If [=!=] <a abstract-op>IsCallable</a>(|F|) is <emu-val>false</emu-val>:
        1.  If the callback function's return type is {{void}}, return.

            Note: This is only possible when the callback function came from an attribute
            marked with [{{TreatNonObjectAsNull}}].

        1.  Return the result of [=converted to an IDL value|converting=]
            <emu-val>undefined</emu-val> to the callback function's return type.
    1.  Let |realm| be |F|'s [=associated Realm=].
    1.  Let |relevant settings| be |realm|'s [=Realm/settings object=].
    1.  Let |stored settings| be |callable|'s [=callback context=].
    1.  [=Prepare to run script=] with |relevant settings|.
    1.  [=Prepare to run a callback=] with |stored settings|.
    1.  Let |esArgs| be the result of [=Web IDL arguments list/converting=] |args| to an ECMAScript
        arguments list. If this throws an exception, set |completion| to the completion value
        representing the thrown exception and jump to the step labeled
        <a href="#invoke-return"><i>return</i></a>.
    1.  Let |callResult| be <a abstract-op>Call</a>(|F|, |thisArg|, |esArgs|).
    1.  If |callResult| is an [=abrupt completion=], set |completion| to
        |callResult| and jump to the step labeled <a href="#invoke-return"><i>return</i></a>.
    1.  Set |completion| to the result of [=converted to an IDL value|converting=]
        |callResult|.\[[Value]] to an IDL value of the same type as the operation’s
        return type.
    1.  <i id="invoke-return">Return:</i> at this
        point |completion| will be set to an ECMAScript completion value.
        1.  [=Clean up after running a callback=] with |stored settings|.
        1.  [=Clean up after running script=] with |relevant settings|.
        1.  If |completion| is a normal completion, return |completion|.
        1.  If |completion| is an [=abrupt completion=] and the callback function has a
            [=return type=] that is <em>not</em> a [=promise type=], return |completion|.
        1.  Let |rejectedPromise| be [=!=] <a abstract-op>Call</a>({{%Promise_reject%}},
            {{%Promise%}}, «|completion|.\[[Value]]»).
        1.  Return the result of [=converted to an IDL value|converting=]
            |rejectedPromise| to the callback function's return type.
</div>

Some callback functions are instead used as [=constructors=]. Such callback functions must not have
a return type that is a [=promise type=].

<div algorithm>

    To <dfn id="construct-a-callback-function" export>construct</dfn> a
    [=callback function type=] value |callable| with a [=Web IDL arguments list=] |args|,
    perform the following steps.
    These steps will either return an IDL value or throw an exception.

    1.  Let |completion| be an uninitialized variable.
    1.  Let |F| be the ECMAScript object corresponding to |callable|.
    1.  If [=!=] <a abstract-op>IsConstructor</a>(|F|) is <emu-val>false</emu-val>, throw a
        {{ECMAScript/TypeError}} exception.
    1.  Let |realm| be |F|'s [=associated Realm=].
    1.  Let |relevant settings| be |realm|'s [=Realm/settings object=].
    1.  Let |stored settings| be |callable|'s [=callback context=].
    1.  [=Prepare to run script=] with |relevant settings|.
    1.  [=Prepare to run a callback=] with |stored settings|.
    1.  Let |esArgs| be the result of [=Web IDL arguments list/converting=] |args| to an ECMAScript
        arguments list. If this throws an exception, set |completion| to the completion value
        representing the thrown exception and jump to the step labeled
        <a href="#construct-return"><i>return</i></a>.
    1.  Let |callResult| be <a abstract-op>Construct</a>(|F|, |esArgs|).
    1.  If |callResult| is an [=abrupt completion=], set |completion| to
        |callResult| and jump to the step labeled <a href="#construct-return"><i>return</i></a>.
    1.  Set |completion| to the result of [=converted to an IDL value|converting=]
        |callResult|.\[[Value]] to an IDL value of the same type as the operation’s
        return type.
    1.  <i id="construct-return">Return:</i> at this
        point |completion| will be set to an ECMAScript completion value.
        1.  [=Clean up after running a callback=] with |stored settings|.
        1.  [=Clean up after running script=] with |relevant settings|.
        1.  Return |completion|.
</div>


<h3 id="es-namespaces">Namespaces</h3>

For every [=namespace=] that is [=exposed=] in a given [=Realm=],
a corresponding property exists on the [=Realm=]'s [=Realm/global object=].
The name of the property is the [=identifier=] of the namespace, and its value is an object
called the <dfn id="dfn-namespace-object" export>namespace object</dfn>.

The characteristics of a namespace object are described in [[#namespace-object]].


<h4 id="namespace-object">Namespace object</h4>

<div algorithm>

    The namespace object for a given [=namespace=] |namespace| and [=Realm=] |realm|
    is <dfn lt="create a namespace object">created</dfn> as follows:

    1.  Let |namespaceObject| be
        [=!=] <a abstract-op>ObjectCreate</a>(|realm|.\[[Intrinsics]].[[{{%ObjectPrototype%}}]]).
    1.  [=Define the regular attributes=] of |namespace| on |namespaceObject| given |realm|.
    1.  [=Define the regular operations=] of |namespace| on |namespaceObject| given |realm|.
    1.  For each [=exposed=] [=interface=] |interface| which has the [{{LegacyNamespace}}] extended
        attribute with the identifier of |namespace| as its argument,
        1.  Let |id| be |interface|'s [=identifier=].
        1.  Let |interfaceObject| be the result of [=create an interface object|creating an
            interface object=] for |interface| with |id| in |realm|.
        1.  Perform [=!=] [$CreateMethodProperty$](|namespaceObject|, |id|, |interfaceObject|).
    1.  Return |namespaceObject|.
</div>


<h3 id="es-exceptions">Exceptions</h3>

<h4 id="es-DOMException-specialness" oldids="es-DOMException-constructor-object, es-DOMException-prototype-object">{{DOMException}} custom bindings</h4>

In the ECMAScript binding, the [=interface prototype object=] for {{DOMException}}
has its \[[Prototype]] [=internal slot=] set to the intrinsic object {{%ErrorPrototype%}},
as defined in the [=create an interface prototype object=] abstract operation.

Additionally, if an implementation gives native {{ECMAScript/Error}} objects special powers or
nonstandard properties (such as a <code>stack</code> property),
it should also expose those on {{DOMException}} instances.

<h4 id="es-exception-objects" dfn>Exception objects</h4>

[=Simple exceptions=] are represented
by native ECMAScript objects of the corresponding type.

A {{DOMException}} is represented by a
[=platform object=] that implements the {{DOMException}} interface.


<h4 id="es-creating-throwing-exceptions">Creating and throwing exceptions</h4>


<div algorithm="to create a simple exception or DOMException">

    To [=create=] a [=simple exception=] or {{DOMException}} |E|, with a string giving the
    [=error name=] |N| for the {{DOMException}} case and optionally a string giving a user
    agent-defined message |M|:

    1.  If |M| was not specified, let |M| be <emu-val>undefined</emu-val>.
    1.  Let |args| be a list of ECMAScript values determined based on the type of |E|:
        <dl class="switch">
             :  |E| is {{DOMException}}
             :: |args| is «|M|, |N|».
             :  |E| is a [=simple exception=]
             :: |args| is «|M|».
        </dl>
    1.  Let |X| be an object determined based on the type of |E|:
        <dl class="switch">
             :  |E| is {{DOMException}}
             :: |X| is the {{DOMException}} [=interface object=]
                from the [=current Realm=].
             :  |E| is a [=simple exception=]
             :: |X| is the [=constructor=] for the corresponding ECMAScript error
                from the [=current Realm=].
        </dl>
    1.  Return [=!=] <a abstract-op>Construct</a>(|X|, |args|).
</div>

<div algorithm="throw an exception">

    To [=exception/throw=] a [=simple exception=] or {{DOMException}}, with a string giving the
    [=error name=] for the {{DOMException}} case and optionally a string giving a user
    agent-defined message:

    1.  Let |O| be the result of [=created|creating an exception=] with the same arguments.
    1.  Throw |O|.
</div>

<div class="note">

    The above algorithms restrict [=Exception objects|objects representing exceptions=] propagating
    out of a [=function object=] to be ones that are associated with the [=Realm=] of that
    [=function object=] (i.e., the [=current Realm=] at the time the function
    executes). For example, consider the IDL:

    <pre highlight="webidl">
        [Exposed=Window]
        interface MathUtils {
          // If x is negative, throws a "<a href="#notsupportederror">NotSupportedError</a>" <a href="dfn-DOMException">DOMException</a>.
          double computeSquareRoot(double x);
        };
    </pre>

    If we apply <code class="idl">computeSquareRoot</code> to a <code class="idl">MathUtils</code>
    object from a different [=Realm=], then the exception thrown will be from the [=Realm=] of the
    method, not the object it is applied to:

    <pre highlight="js">
        const myMU = window.getMathUtils();          // A MathUtils object from this Realm
        const otherMU = otherWindow.getMathUtils();  // A MathUtils object from a different Realm

        myMU instanceof Object;                      // Evaluates to true.
        otherMU instanceof Object;                   // Evaluates to false.
        otherMU instanceof otherWindow.Object;       // Evaluates to true.

        try {
          otherMU.doComputation.call(myMU, -1);
        } catch (e) {
          console.assert(!(e instanceof DOMException));
          console.assert(e instanceof otherWindow.DOMException);
        }
    </pre>
</div>


<h4 id="es-handling-exceptions">Handling exceptions</h4>

Unless specified otherwise,
whenever ECMAScript runtime semantics are invoked due
to requirements in this document and
end due to an exception being thrown, that exception
must propagate to the caller, and if
not caught there, to its caller, and so on.

Per [[#conventions]], an algorithm specified in this document may intercept thrown exceptions, either by specifying
the exact steps to take if <dfn>an exception was thrown</dfn>, or by explicitly handling [=abrupt completions=].

<div class="example">

    The following [=IDL fragment=]
    defines two [=interfaces=]
    and an [=exception=].
    The <code>valueOf</code> attribute on <code class="idl">ExceptionThrower</code>
    is defined to throw an exception whenever an attempt is made
    to get its value.

    <pre highlight="webidl">
        [Exposed=Window]
        interface Dahut {
          attribute DOMString type;
        };

        [Exposed=Window]
        interface ExceptionThrower {
          // This attribute always throws a NotSupportedError and never returns a value.
          attribute long valueOf;
        };
    </pre>

    Assuming an ECMAScript implementation supporting this interface,
    the following code demonstrates how exceptions are handled:

    <pre highlight="js">
        var d = getDahut();              // Obtain an instance of Dahut.
        var et = getExceptionThrower();  // Obtain an instance of ExceptionThrower.

        try {
          d.type = { toString: function() { throw "abc"; } };
        } catch (e) {
          // The string "abc" is caught here, since as part of the conversion
          // from the native object to a string, the anonymous function
          // was invoked, and none of the [[DefaultValue]], ToPrimitive or
          // ToString algorithms are defined to catch the exception.
        }

        try {
          d.type = { toString: { } };
        } catch (e) {
          // An exception is caught here, since an attempt is made to invoke
          // [[Call]] on the native object that is the value of toString
          // property.
        }

        try {
          d.type = Symbol();
        } catch (e) {
          // An exception is caught here, since an attempt is made to invoke
          // the ECMAScript ToString abstract operation on a Symbol value.
        }

        d.type = et;
        // An uncaught "NotSupportedError" DOMException is thrown here, since the
        // [[DefaultValue]] algorithm attempts to get the value of the
        // "valueOf" property on the ExceptionThrower object.  The exception
        // propagates out of this block of code.
    </pre>
</div>


<h3 id="synthetic-module-records">Synthetic module records</h3>

A <dfn export>Synthetic Module Record</dfn> is used to represent information about a module that is
defined by specifications.
The set of exported names is static, and determined at creation time (as an argument to
[$CreateSyntheticModule$]), while the set of exported values can be changed over time using
[$SetSyntheticModuleExport$].
It has no imports or dependencies.

Note: A [=Synthetic Module Record=] could be used for defining a variety of module types: for
example, built-in modules, or JSON modules, or CSS modules.

Note: [=Synthetic Module Records=] are being developed in concert with the authors of the
<cite>JavaScript Standard Library</cite> proposal, and might eventually move to the ECMAScript
specification. [[JSSTDLIB]] [[ECMA-262]].

In addition to the [=Module Record Fields=], Synthetic Module Records have the additional fields
listed below.
Each of these fields is initially set in [$CreateSyntheticModule$].

<table id="table-synthetic-module-record-fields" class="data">
<caption>Additional Fields of Synthetic Module Records</caption>
<thead>
  <tr>
    <th>Field Name
    <th>Value Type
    <th>Meaning
<tbody>
  <tr>
    <td>\[[ExportNames]]
    <td>List of String
    <td>A List of all names that are exported.
  <tr>
    <td>\[[EvaluationSteps]]
    <td>An abstract operation
    <td>An abstract operation that will be performed upon evaluation of the module, taking the
        [=Synthetic Module Record=] as its sole argument.
        These will usually set up the exported values, by using [$SetSyntheticModuleExport$].
        They must not modify \[[ExportNames]].
        They may return an abrupt completion.
</table>

<h4 id="createsyntheticmodule">CreateSyntheticModule</h4>

<div algorithm>
The abstract operation <dfn abstract-op>CreateSyntheticModule</dfn>(|exportNames|, |evaluationSteps|, |realm|, |hostDefined|) creates a [=Synthetic Module Record=] based upon
the given exported names and evaluation steps.
It performs the following steps:

    1.  Return [=Synthetic Module Record=] {
            \[[Realm]]: |realm|,
            \[[Environment]]: <emu-val>undefined</emu-val>,
            \[[Namespace]]: <emu-val>undefined</emu-val>,
            \[[HostDefined]]: |hostDefined|,
            \[[ExportNames]]: |exportNames|,
            \[[EvaluationSteps]]: |evaluationSteps|
        }.
</div>

Note: we could set up \[[Environment]] either here or in [$Synthetic Module Record/Link$]().
It is done in [$Synthetic Module Record/Link$]() for symmetry with [=Source Text Module Records=],
but there is no observable difference.

<h4 id="setsyntheticmoduleexport">SetSyntheticModuleExport</h4>

<div algorithm>
The abstract operation <dfn abstract-op>SetSyntheticModuleExport</dfn>(|module|, |exportName|,
|exportValue|) can be used to set or change the exported value for a pre-established export of a
Synthetic Module Record.
It performs the following steps:

    1.  Let |envRec| be |module|.\[[Environment]]'s [=Lexical Environment/EnvironmentRecord=].
    1.  Perform |envRec|.[$Environment Record/SetMutableBinding$](|exportName|, |exportValue|,
        <emu-val>true</emu-val>).
</div>

<h4 id="smr-concrete-methods">Concrete Methods</h4>

The following are the concrete methods for [=Synthetic Module Record=] that implement the
corresponding [=Module Record=] abstract methods.

<h5 id="smr-getexportednames">GetExportedNames</h5>

<div algorithm>
The <dfn abstract-op for="Synthetic Module Record">GetExportedNames</dfn>(<var
ignore>exportStarSet</var>) concrete method of a [=Synthetic Module Record=] implements the
corresponding [=Module Record=] abstract method.

It performs the following steps:

    1.  Let |module| be this [=Synthetic Module Record=].
    1.  Return |module|.\[[ExportNames]].
</div>

<h5 id="smr-resolveexport">ResolveExport</h5>

<div algorithm>
The <dfn abstract-op for="Synthetic Module Record">ResolveExport</dfn>(|exportName|, <var
ignore>resolveSet</var>) concrete method of a [=Synthetic Module Record=] implements the
corresponding [=Module Record=] abstract method.

It performs the following steps:

    1.  Let |module| be this [=Synthetic Module Record=].
    1.  If |module|.\[[ExportNames]] does not contain |exportName|, return <emu-val>null</emu-val>.
    1.  Return [=ResolvedBinding Record=] { \[[Module]]: |module|, \[[BindingName]]: |exportName| }.
</div>

<h5 id="smr-Link">Link</h5>

<div algorithm>
The <dfn abstract-op for="Synthetic Module Record">Link</dfn>() concrete method of a
[=Synthetic Module Record=] implements the corresponding [=Module Record=] abstract method.

It performs the following steps:

    1.  Let |module| be this [=Synthetic Module Record=].
    1.  Let |realm| be |module|.\[[Realm]].
    1.  Assert: |realm| is not <emu-val>undefined</emu-val>.
    1.  Let |env| be [$NewModuleEnvironment$](|realm|.\[[GlobalEnv]]).
    1.  Set |module|.\[[Environment]] to |env|.
    1.  Let |envRec| be |env|'s [=Lexical Environment/EnvironmentRecord=].
    1.  For each |exportName| in |module|.\[[ExportNames]],
        1.  Perform [=!=] |envRec|.[$Environment Record/CreateMutableBinding$](|exportName|,
            <emu-val>false</emu-val>).
        1.  Perform [=!=] |envRec|.[$Environment Record/InitializeBinding$](|exportName|,
            <emu-val>undefined</emu-val>).
    1.  Return <emu-val>undefined</emu-val>.
</div>

<h5 id="smr-evaluate">Evaluate</h5>

<div algorithm>
The <dfn abstract-op for="Synthetic Module Record">Evaluate</dfn>() concrete method of a
[=Synthetic Module Record=] implements the corresponding [=Module Record=] abstract method.

It performs the following steps:

    1.  Let |module| be this [=Synthetic Module Record=].
    1.  Let |moduleCxt| be a new [=ECMAScript code execution context=].
    1.  Set the [=Execution context/Function=] of |moduleCxt| to <emu-val>null</emu-val>.
    1.  Assert: |module|.\[[Realm]] is not <emu-val>undefined</emu-val>.
    1.  Set the [=Execution context/Realm=] of |moduleCxt| to |module|.\[[Realm]].
    1.  Set the [=Execution context/ScriptOrModule=] of |moduleCxt| to |module|.
    1.  Set the [=ECMAScript code execution context/VariableEnvironment=] of |moduleCxt| to
        |module|.\[[Environment]].
    1.  Set the [=ECMAScript code execution context/LexicalEnvironment=] of |moduleCxt| to
        |module|.\[[Environment]].
    1.  Suspend the currently [=running execution context=].
    1.  Push |moduleCxt| on to the [=execution context stack=]; |moduleCxt| is now the
        [=running execution context=].
    1.  Let |completion| be the result of performing |module|.\[[EvaluationSteps]](|module|).
    1.  Suspend |moduleCxt| and remove it from the [=execution context stack=].
    1.  Resume the context that is now on the top of the [=execution context stack=] as the
        [=running execution context=].
    1.  Return [$Completion$](|completion|).
</div>


<h2 id="common">Common definitions</h2>

This section specifies some common definitions that all
[=conforming implementations=]
must support.


<h3 id="ArrayBufferView" typedef oldids="common-ArrayBufferView">ArrayBufferView</h3>

<pre class="idl">
    typedef (Int8Array or Int16Array or Int32Array or
             Uint8Array or Uint16Array or Uint32Array or Uint8ClampedArray or
             Float32Array or Float64Array or DataView) ArrayBufferView;
</pre>

The {{ArrayBufferView}} typedef is used to represent
objects that provide a view on to an {{ArrayBuffer}}.


<h3 id="BufferSource" typedef oldids="common-BufferSource">BufferSource</h3>

<pre class="idl">typedef (ArrayBufferView or ArrayBuffer) BufferSource;</pre>

The {{BufferSource}} typedef is used to represent objects
that are either themselves an {{ArrayBuffer}} or which
provide a view on to an {{ArrayBuffer}}.

<h3 id="idl-DOMException" interface oldids="dfn-DOMException">DOMException</h4>

The {{DOMException}} type is an [=interface type=] defined by the following IDL
fragment:

<pre class="idl">
[Exposed=(Window,Worker),
 Serializable]
interface DOMException { // but see below note about ECMAScript binding
  constructor(optional DOMString message = "", optional DOMString name = "Error");
  readonly attribute DOMString name;
  readonly attribute DOMString message;
  readonly attribute unsigned short code;

  const unsigned short INDEX_SIZE_ERR = 1;
  const unsigned short DOMSTRING_SIZE_ERR = 2;
  const unsigned short HIERARCHY_REQUEST_ERR = 3;
  const unsigned short WRONG_DOCUMENT_ERR = 4;
  const unsigned short INVALID_CHARACTER_ERR = 5;
  const unsigned short NO_DATA_ALLOWED_ERR = 6;
  const unsigned short NO_MODIFICATION_ALLOWED_ERR = 7;
  const unsigned short NOT_FOUND_ERR = 8;
  const unsigned short NOT_SUPPORTED_ERR = 9;
  const unsigned short INUSE_ATTRIBUTE_ERR = 10;
  const unsigned short INVALID_STATE_ERR = 11;
  const unsigned short SYNTAX_ERR = 12;
  const unsigned short INVALID_MODIFICATION_ERR = 13;
  const unsigned short NAMESPACE_ERR = 14;
  const unsigned short INVALID_ACCESS_ERR = 15;
  const unsigned short VALIDATION_ERR = 16;
  const unsigned short TYPE_MISMATCH_ERR = 17;
  const unsigned short SECURITY_ERR = 18;
  const unsigned short NETWORK_ERR = 19;
  const unsigned short ABORT_ERR = 20;
  const unsigned short URL_MISMATCH_ERR = 21;
  const unsigned short QUOTA_EXCEEDED_ERR = 22;
  const unsigned short TIMEOUT_ERR = 23;
  const unsigned short INVALID_NODE_TYPE_ERR = 24;
  const unsigned short DATA_CLONE_ERR = 25;
};
</pre>

Note: as discussed in [[#es-DOMException-specialness]], the ECMAScript binding imposes additional
requirements beyond the normal ones for [=interface types=].

Each {{DOMException}} object has an associated <dfn for="DOMException">name</dfn> and
<dfn for="DOMException">message</dfn>, both [=JavaScript strings=].

The <dfn constructor for="DOMException"><code>DOMException(|message|, |name|)</code></dfn>
constructor, when invoked, must run these steps:

1. Set <b>this</b>'s [=DOMException/name=] to |name|.
1. Set <b>this</b>'s [=DOMException/message=] to |message|.

The <dfn attribute for="DOMException"><code>name</code></dfn> attribute's getter must return this
{{DOMException}} object's [=DOMException/name=].

The <dfn attribute for="DOMException"><code>message</code></dfn> attribute's getter must return this
{{DOMException}} object's [=DOMException/message=].

The <dfn attribute for="DOMException"><code>code</code></dfn> attribute's getter must return the
legacy code indicated in the [=error names table=] for this {{DOMException}} object's
[=DOMException/name=], or 0 if no such entry exists in the table.

{{DOMException}} objects are [=serializable objects=].

Their [=serialization steps=], given <var>value</var> and <var>serialized</var>, are:

<ol>
    <li>Set <var>serialized</var>.\[[Name]] to <var>value</var>'s [=DOMException/name=].</li>
    <li>Set <var>serialized</var>.\[[Message]] to <var>value</var>'s [=DOMException/message=].</li>
    <li>User agents should attach a serialized representation of any interesting accompanying data
    which are not yet specified, notably the <code>stack</code> property, to
    <var>serialized</var>.</li>
</ol>

Their [=deserialization steps=], given <var>value</var> and <var>serialized</var>, are:

<ol>
    <li>Set <var>value</var>'s [=DOMException/name=] to <var>serialized</var>.\[[Name]].</li>
    <li>Set <var>value</var>'s [=DOMException/message=] to <var>serialized</var>.\[[Message]].</li>
    <li>If any other data is attached to <var>serialized</var>, then deserialize and attach it to
    <var>value</var>.</li>
</ol>

<h3 id="DOMTimeStamp" typedef oldids="common-DOMTimeStamp">DOMTimeStamp</h3>

<pre class="idl">typedef unsigned long long DOMTimeStamp;</pre>

The {{DOMTimeStamp}} type is used for representing
a number of milliseconds, either as an absolute time (relative to some epoch)
or as a relative amount of time.  Specifications that use this type will need
to define how the number of milliseconds is to be interpreted.


<h3 id="Function" callback oldids="common-Function">Function</h3>

<pre class="idl">callback Function = any (any... arguments);</pre>

The {{Function}} [=callback function=]
type is used for representing function values with no restriction on what arguments
are passed to it or what kind of value is returned from it.


<h3 id="VoidFunction" callback>VoidFunction</h3>

<pre class="idl">callback VoidFunction = void ();</pre>

The {{VoidFunction}} [=callback function=]
type is used for representing function values that take no arguments and do not
return any value.


<h2 id="extensibility">Extensibility</h2>

<i>This section is informative.</i>

Extensions to language binding requirements can be specified
using [=extended attributes=]
that do not conflict with those defined in this document.  Extensions for
private, project-specific use should not be included in
[=IDL fragments=]
appearing in other specifications.  It is recommended that extensions
that are required for use in other specifications be coordinated
with the group responsible for work on <cite>Web IDL</cite>, which
at the time of writing is the
<a href="http://www.w3.org/WebPlatform/WG/">W3C Web Platform Working Group</a>,
for possible inclusion in a future version of this document.

Extensions to any other aspect of the IDL language are
strongly discouraged.


<h2 id="legacy-constructs">Legacy constructs</h4>

<i>This section is informative.</i>

Legacy WebIDL constructs exist only so that
legacy Web platform features can be specified.
They are generally prefixed with the "<code>Legacy</code>" string.
It is strongly discouraged to use legacy WebIDL constructs in specifications
unless required to specify the behavior of legacy Web platform features,
or for consistency with such features.
Editors who wish to use legacy WebIDL constructs are strongly advised to discuss this
by <a href="https://github.com/heycam/webidl/issues/new?title=Intent%20to%20use%20a%20legacy%20WebIDL%20construct">filing an issue</a>
before proceeding.

Marking a construct as legacy does not, in itself,
imply that it is about to be removed from this specification.
It does suggest however, that it is a good candidate
for future removal from this specification,
whenever various heuristics indicate that
the Web platform features it helps specify can be removed altogether
or can be modified to rely on non-legacy WebIDL constructs instead.


<h2 id="referencing">Referencing this specification</h2>

<i>This section is informative.</i>

It is expected that other specifications that define Web platform interfaces
using one or more [=IDL fragments=]
will reference this specification.  It is suggested
that those specifications include a sentence such as the following,
to indicate that the IDL is to be interpreted as described in this
specification:

<blockquote>

    The IDL fragment in Appendix A of this specification must, in conjunction
    with the IDL fragments defined in this specification's normative references,
    be interpreted as required for <em>conforming sets of IDL fragments</em>, as described in the
    “Web IDL” specification. \[WEBIDL]

</blockquote>

In addition, it is suggested that the conformance class for user
agents in referencing specifications be linked to the
[=conforming implementation=] class from this specification:

<blockquote>

    A conforming FooML user agent must also be a
    <em>conforming implementation</em> of the IDL fragment in Appendix A
    of this specification, as described in the
    “Web IDL” specification. \[WEBIDL]

</blockquote>


<h2 id="priv-sec">Privacy and Security Considerations</h2>

This specification defines a conversion layer between JavaScript and IDL values. An incorrect
implementation of this layer can lead to security issues.

This specification also provides the ability to use JavaScript values directly, through the
{{any}} and {{object}} IDL types. These values need to be handled carefully to avoid security
issues. In particular, user script can run in response to nearly any manipulation of these values,
and invalidate the expectations of specifications or implementations using them.

This specification makes it possible to interact with {{SharedArrayBuffer}} objects, which can be
used to build timing attacks. Specifications that use these objects need to consider such attacks.


<h2 id="acknowledgements">Acknowledgements</h2>

<i>This section is informative.</i>

The editor would like to thank the following people for contributing
to this specification:
Glenn Adams,
David Andersson,
Jake Archibald,
L. David Baron,
Art Barstow,
Nils Barth,
Robin Berjon,
David Bruant,
Jan-Ivar Bruaroey,
Marcos Cáceres,
Giovanni Campagna,
Domenic Denicola,
Chris Dumez,
Michael Dyck,
Daniel Ehrenberg,
Brendan Eich,
João Eiras,
Gorm Haug Eriksen,
Sigbjorn Finne,
David Flanagan,
Aryeh Gregor,
Dimitry Golubovsky,
James Graham,
Aryeh Gregor,
Tiancheng “Timothy” Gu,
Kartikaya Gupta,
Marcin Hanclik,
Jed Hartman,
Stefan Haustein,
Dominique Hazaël-Massieux,
Ian Hickson,
Björn Höhrmann,
Kyle Huey,
Lachlan Hunt,
Oliver Hunt,
Jim Jewett,
Wolfgang Keller,
Anne van Kesteren,
Olav Junker Kjær,
Takayoshi Kochi,
Magnus Kristiansen,
Takeshi Kurosawa,
Yves Lafon,
Travis Leithead,
Jim Ley,
Kevin Lindsey,
Jens Lindström,
Peter Linss,
呂康豪 (Kang-Hao Lu),
Kyle Machulis,
Darien Maillet Valentine,
Mark Miller,
Ms2ger,
Andrew Oakley,
岡坂 史紀 (Shiki Okasaka),
Jason Orendorff,
Olli Pettay,
Simon Pieters,
Andrei Popescu,
François Remy,
Tim Renouf,
Tim Ruffles,
Alex Russell,
Takashi Sakamoto,
Doug Schepers,
Jonas Sicking,
Garrett Smith,
Sam Sneddon,
Jungkee Song,
Josh Soref,
Maciej Stachowiak,
Anton Tayanovskyy,
triple-underscore,
Peter Van der Beken,
Jeff Walden,
Allen Wirfs-Brock,
Jeffrey Yasskin and,
Collin Xu.

Special thanks also go to Sam Weinig for maintaining this document
while the editor was unavailable to do so.


<h2 id="idl-grammar" class="no-num">IDL grammar</h2>

This section defines an LL(1) grammar whose start symbol,
<emu-nt><a href="#prod-Definitions">Definitions</a></emu-nt>, matches an
entire [=IDL fragment=].

Each production in the grammar has on its right hand side either a
non-zero sequence of terminal and non-terminal symbols, or an
epsilon (ε) which indicates no symbols.
Symbols that begin with an uppercase letter are non-terminal symbols.
Symbols in monospaced fonts are terminal symbols.
Symbols in sans-serif font that begin with a lowercase letter are terminal
symbols that are matched by the regular expressions (using Perl 5 regular
expression syntax [[!PERLRE]]) as follows:

<table class="grammar data">
    <tr>
        <td id="prod-integer"><emu-t class="regex">integer</emu-t></td>
        <td><code>=</code></td>
        <td><code class="regex"><span class="mute">/</span>-?([1-9][0-9]*|0[Xx][0-9A-Fa-f]+|0[0-7]*)<span class="mute">/</span></code></td>
    </tr>
    <tr>
        <td id="prod-decimal"><emu-t class="regex">decimal</emu-t></td>
        <td><code>=</code></td>
        <td><code class="regex"><span class="mute">/</span>-?(([0-9]+\.[0-9]*|[0-9]*\.[0-9]+)([Ee][+-]?[0-9]+)?|[0-9]+[Ee][+-]?[0-9]+)<span class="mute">/</span></code></td>
    </tr>
    <tr>
        <td id="prod-identifier"><emu-t class="regex">identifier</emu-t></td>
        <td><code>=</code></td>
        <td><code class="regex"><span class="mute">/</span>[_-]?[A-Za-z][0-9A-Z_a-z-]*<span class="mute">/</span></code></td>
    </tr>
    <tr>
        <td id="prod-string"><emu-t class="regex">string</emu-t></td>
        <td><code>=</code></td>
        <td><code class="regex"><span class="mute">/</span>"[^"]*"<span class="mute">/</span></code></td>
    </tr>
    <tr>
        <td id="prod-whitespace"><emu-t class="regex">whitespace</emu-t></td>
        <td><code>=</code></td>
        <td><code class="regex"><span class="mute">/</span>[\t\n\r ]+<span class="mute">/</span></code></td>
    </tr>
    <tr>
        <td id="prod-comment"><emu-t class="regex">comment</emu-t></td>
        <td><code>=</code></td>
        <td><code class="regex"><span class="mute">/</span><span class="mute">\</span>/<span class="mute">\</span>/.*|<span class="mute">\</span>/\*(.|\n)*?\*<span class="mute">\</span>/<span class="mute">/</span></code></td>
    </tr>
    <tr>
        <td id="prod-other"><emu-t class="regex">other</emu-t></td>
        <td><code>=</code></td>
        <td><code class="regex"><span class="mute">/</span>[^\t\n\r 0-9A-Za-z]<span class="mute">/</span></code></td>
    </tr>
</table>

The tokenizer operates on a sequence of Unicode characters
[[!UNICODE]].
When tokenizing, the longest possible match must be used.  For example, if the input
text is “<span class="input">a1</span>”, it is tokenized as a single <emu-t class="regex"><a href="#prod-identifier">identifier</a></emu-t>,
and not as a separate <emu-t class="regex"><a href="#prod-identifier">identifier</a></emu-t> and <emu-t class="regex"><a href="#prod-integer">integer</a></emu-t>.
If the longest possible match could match one of the above named terminal symbols or
one of the other terminal symbols from the grammar, it must be tokenized as the latter.
Thus, the input text “<span class="input">long</span>” is tokenized as the quoted terminal symbol
<emu-t>long</emu-t> rather than an <emu-t class="regex"><a href="#prod-identifier">identifier</a></emu-t> called "<code>long</code>",
and “<span class="input">.</span>” is tokenized as the quoted terminal symbol
<emu-t>.</emu-t> rather than an <emu-t class="regex"><a href="#prod-other">other</a></emu-t>.

The IDL syntax is case sensitive, both for the quoted terminal symbols
used in the grammar and the values used for
<emu-t class="regex"><a href="#prod-identifier">identifier</a></emu-t> terminals.  Thus, for
example, the input text “<span class="input">Const</span>” is tokenized as
an <emu-t class="regex"><a href="#prod-identifier">identifier</a></emu-t> rather than the
terminal symbol <emu-t>const</emu-t>, an
[=interface=] with
[=identifier=]
"<code>A</code>" is distinct from one named "<code>a</code>", and an
[=extended attribute=]
[<code class="idl">namedconstructor</code>] will not be recognized as
the [{{NamedConstructor}}]
extended attribute.

Implicitly, any number of <emu-t class="regex"><a href="#prod-whitespace">whitespace</a></emu-t> and
<emu-t class="regex"><a href="#prod-comment">comment</a></emu-t> terminals are allowed between every other terminal
in the input text being parsed.  Such <emu-t class="regex"><a href="#prod-whitespace">whitespace</a></emu-t> and
<emu-t class="regex"><a href="#prod-comment">comment</a></emu-t> terminals are ignored while parsing.

The following LL(1) grammar, starting with <emu-nt><a href="#prod-Definitions">Definitions</a></emu-nt>,
matches an [=IDL fragment=]:

<div data-fill-with="grammar-index"></div>

Note: The <emu-nt><a href="#prod-Other">Other</a></emu-nt>
non-terminal matches any single terminal symbol except for
<emu-t>(</emu-t>, <emu-t>)</emu-t>,
<emu-t>[</emu-t>, <emu-t>]</emu-t>,
<emu-t>{</emu-t>, <emu-t>}</emu-t>
and <emu-t>,</emu-t>.

While the <emu-nt><a href="#prod-ExtendedAttribute">ExtendedAttribute</a></emu-nt>
non-terminal matches any non-empty sequence of terminal symbols (as long as any
parentheses, square brackets or braces are balanced, and the
<emu-t>,</emu-t> token appears only within those balanced brackets),
only a subset of those
possible sequences are used by the [=extended attributes=]
defined in this specification — see
[[#idl-extended-attributes]]
for the syntaxes that are used by these extended attributes.


<h2 id="conventions" class="no-num">Document conventions</h3>

The following typographic conventions are used in this document:

*   Defining instances of terms: <dfn id="dfn-example-term">example term</dfn>
*   Links to terms defined in this document or elsewhere: [=example term=]
*   Grammar terminals: <emu-t>sometoken</emu-t>
*   Grammar non-terminals: <emu-nt>ExampleGrammarNonTerminal</emu-t>
*   Grammar symbols: <emu-t class="regex">identifier</emu-t>
*   IDL types: {{unsigned long}}
*   ECMAScript classes: {{ECMAScript/Map}}
*   ECMAScript language types: Object
*   Code snippets: <code>a = b + obj.f()</code>
*   Unicode characters: <span class="char">U+0030 DIGIT ZERO ("0")</span>
*   Extended attributes: [<code class="idl">ExampleExtendedAttribute</code>]
*   Variable names in prose and algorithms: <var ignore>exampleVariableName</var>.
*   IDL informal syntax examples:
    <pre highlight="webidl" class="syntax">
        [extended_attributes]
        interface identifier {
          <mark>/* interface_members... */</mark>
        };
    </pre>

    (Specific parts of the syntax discussed in surrounding prose are <mark>highlighted</mark>.)
*   IDL grammar snippets:
    <pre class="grammar no-index">
        ExampleGrammarNonTerminal :
            OtherNonTerminal "sometoken"
            other AnotherNonTerminal
            ε  // nothing
    </pre>
*   Non-normative notes:

    Note: This is a note.

*   Non-normative examples:
    <div class="example">
        This is an example.
    </div>
*   Normative warnings:
    <p class="advisement">
        This is a warning.
    </p>
*   Code blocks:
    <pre highlight="webidl">
        // This is an IDL code block.
        [Exposed=Window]
        interface Example {
          attribute long something;
        };
    </pre>
    <pre highlight="js">
        // This is an ECMAScript code block.
        window.onload = function() { window.alert("loaded"); };
    </pre>

The following conventions are used in the algorithms in this document:

*   Algorithms use the [=ECMAScript/conventions=] of the ECMAScript specification,
    including the [=!=] and [=?=] notation for unwrapping [=Completion Records=].
*   Algorithms sometimes treat returning/throwing values and returning [=Completion Records=]
    interchangeably. That is, an algorithm that uses return/throw terminology may be treated as
    returning a [=Completion Record=], while one that returns a [=Completion Record=] may be treated as
    returning a value or throwing an exception. Similarly, to catch exceptions, defining the
    behavior to adopt when [=an exception was thrown=] and checking if the [=Completion Record=]’s
    \[[Type]] field is “throw” are equivalent.
*   [=Completion Records=] are extended by allowing them to contain values that are not ECMAScript
    values, such as Web IDL values.


<h2 id="conformance" class="no-num" oldids="conformant-algorithms">Conformance</h2>

Everything in this specification is normative except for diagrams,
examples, notes and sections marked as being informative.

This specification depends on the Infra Standard. [[!INFRA]]

The following conformance classes are defined by this specification:

 :  <dfn id="dfn-conforming-set-of-idl-fragments" export>conforming set of IDL fragments</dfn>
 :: A set of [=IDL fragments=] is considered
    to be a [=conforming set of IDL fragments=] if, taken together, they satisfy all of the
    must-,
    required- and shall-level
    criteria in this specification that apply to IDL fragments.
 :  <dfn id="dfn-conforming-implementation" export>conforming implementation</dfn>
 :: A user agent is considered to be a
    [=conforming implementation=]
    relative to a [=conforming set of IDL fragments=] if it satisfies all of the must-,
    required- and shall-level
    criteria in this specification that apply to implementations for all language
    bindings that the user agent supports.
 :  <dfn id="dfn-conforming-ecmascript-implementation" export>conforming ECMAScript implementation</dfn>
 :: A user agent is considered to be a
    [=conforming ECMAScript implementation=]
    relative to a [=conforming set of IDL fragments=] if it satisfies all of the must-,
    required- and shall-level
    criteria in this specification that apply to implementations for the ECMAScript
    language binding.

<script class="remove">
    // Grammar
    (function() {
        function wrap(s) { return "<pre class=grammar>" + s + "</pre>"; }
        var output = "";
        [].forEach.call(document.querySelectorAll("pre.grammar"), pre => {
            var html = pre.textContent.replace(/("[^"]+")|([a-zA-Z]+)|(:)/g, m => {
                if (/^"/.test(m)) { return "<emu-t>" + m.replace(/^"|"$/g, "") + "</emu-t>"; }
                if (/^(integer|decimal|identifier|string|whitespace|comment|other)$/.test(m)) {
                  return "<emu-t class=\"regex\"><a href=\"#prod-" + m + "\">" + m + "</a></emu-t>";
                }
                if (m == ":") { return "::"; }
                if (document.querySelector("#prod-" + m)) {
                  return "<emu-nt><a href=\"#prod-" + m + "\">" + m + "</a></emu-nt>";
                }
                return "<emu-nt>" + m + "</emu-nt>"
            });

            pre.innerHTML = html;
            var fillWith = document.querySelectorAll("div[data-fill-with=\"grammar-" + pre.id.replace("prod-", "") + "\"]");
            [].forEach.call(fillWith, div => div.innerHTML = wrap(html));

            if (!(/\bno-index\b/).test(pre.className)) {
              output += html.replace(/<emu-nt>/, "<emu-nt id=\"" + pre.id.replace("prod-", "index-prod-") + "\">")
                .replace(/#prod-([^a-z])/g, "#index-prod-$1") + "\n";
            }
        });
        document.querySelector("div[data-fill-with=\"grammar-index\"]").innerHTML = wrap(output);
    })();
</script>

<script>
    // Rotated Table Headers
    /*! modernizr 3.3.1 (Custom Build) | MIT *
     * https://modernizr.com/download/?-csstransforms-setclasses !*/
    !function(e,n,t){function r(e,n){return typeof e===n}function o(){var e,n,t,o,s,i,a;for(var l in C)if(C.hasOwnProperty(l)){if(e=[],n=C[l],n.name&&(e.push(n.name.toLowerCase()),n.options&&n.options.aliases&&n.options.aliases.length))for(t=0;t<n.options.aliases.length;t++)e.push(n.options.aliases[t].toLowerCase());for(o=r(n.fn,"function")?n.fn():n.fn,s=0;s<e.length;s++)i=e[s],a=i.split("."),1===a.length?Modernizr[a[0]]=o:(!Modernizr[a[0]]||Modernizr[a[0]]instanceof Boolean||(Modernizr[a[0]]=new Boolean(Modernizr[a[0]])),Modernizr[a[0]][a[1]]=o),g.push((o?"":"no-")+a.join("-"))}}function s(e){var n=_.className,t=Modernizr._config.classPrefix||"";if(S&&(n=n.baseVal),Modernizr._config.enableJSClass){var r=new RegExp("(^|\\s)"+t+"no-js(\\s|$)");n=n.replace(r,"$1"+t+"js$2")}Modernizr._config.enableClasses&&(n+=" "+t+e.join(" "+t),S?_.className.baseVal=n:_.className=n)}function i(e,n){return!!~(""+e).indexOf(n)}function a(){return"function"!=typeof n.createElement?n.createElement(arguments[0]):S?n.createElementNS.call(n,"http://www.w3.org/2000/svg",arguments[0]):n.createElement.apply(n,arguments)}function l(e){return e.replace(/([a-z])-([a-z])/g,function(e,n,t){return n+t.toUpperCase()}).replace(/^-/,"")}function f(e,n){return function(){return e.apply(n,arguments)}}function u(e,n,t){var o;for(var s in e)if(e[s]in n)return t===!1?e[s]:(o=n[e[s]],r(o,"function")?f(o,t||n):o);return!1}function d(e){return e.replace(/(\[A-Z])/g,function(e,n){return"-"+n.toLowerCase()}).replace(/^ms-/,"-ms-")}function c(){var e=n.body;return e||(e=a(S?"svg":"body"),e.fake=!0),e}function p(e,t,r,o){var s,i,l,f,u="modernizr",d=a("div"),p=c();if(parseInt(r,10))for(;r--;)l=a("div"),l.id=o?o[r]:u+(r+1),d.appendChild(l);return s=a("style"),s.type="text/css",s.id="s"+u,(p.fake?p:d).appendChild(s),p.appendChild(d),s.styleSheet?s.styleSheet.cssText=e:s.appendChild(n.createTextNode(e)),d.id=u,p.fake&&(p.style.background="",p.style.overflow="hidden",f=_.style.overflow,_.style.overflow="hidden",_.appendChild(p)),i=t(d,e),p.fake?(p.parentNode.removeChild(p),_.style.overflow=f,_.offsetHeight):d.parentNode.removeChild(d),!!i}function m(n,r){var o=n.length;if("CSS"in e&&"supports"in e.CSS){for(;o--;)if(e.CSS.supports(d(n[o]),r))return!0;return!1}if("CSSSupportsRule"in e){for(var s=[];o--;)s.push("("+d(n[o])+":"+r+")");return s=s.join(" or "),p("@supports ("+s+") { #modernizr { position: absolute; } }",function(e){return"absolute"==getComputedStyle(e,null).position})}return t}function h(e,n,o,s){function f(){d&&(delete z.style,delete z.modElem)}if(s=r(s,"undefined")?!1:s,!r(o,"undefined")){var u=m(e,o);if(!r(u,"undefined"))return u}for(var d,c,p,h,v,y=["modernizr","tspan","samp"];!z.style&&y.length;)d=!0,z.modElem=a(y.shift()),z.style=z.modElem.style;for(p=e.length,c=0;p>c;c++)if(h=e[c],v=z.style[h],i(h,"-")&&(h=l(h)),z.style[h]!==t){if(s||r(o,"undefined"))return f(),"pfx"==n?h:!0;try{z.style[h]=o}catch(g){}if(z.style[h]!=v)return f(),"pfx"==n?h:!0}return f(),!1}function v(e,n,t,o,s){var i=e.charAt(0).toUpperCase()+e.slice(1),a=(e+" "+b.join(i+" ")+i).split(" ");return r(n,"string")||r(n,"undefined")?h(a,n,o,s):(a=(e+" "+E.join(i+" ")+i).split(" "),u(a,n,t))}function y(e,n,r){return v(e,t,t,n,r)}var g=[],C=[],w={_version:"3.3.1",_config:{classPrefix:"",enableClasses:!0,enableJSClass:!0,usePrefixes:!0},_q:[],on:function(e,n){var t=this;setTimeout(function(){n(t[e])},0)},addTest:function(e,n,t){C.push({name:e,fn:n,options:t})},addAsyncTest:function(e){C.push({name:null,fn:e})}},Modernizr=function(){};Modernizr.prototype=w,Modernizr=new Modernizr;var _=n.documentElement,S="svg"===_.nodeName.toLowerCase(),x="Moz O ms Webkit",b=w._config.usePrefixes?x.split(" "):[];w._cssomPrefixes=b;var E=w._config.usePrefixes?x.toLowerCase().split(" "):[];w._domPrefixes=E;var P={elem:a("modernizr")};Modernizr._q.push(function(){delete P.elem});var z={style:P.elem.style};Modernizr._q.unshift(function(){delete z.style}),w.testAllProps=v,w.testAllProps=y,Modernizr.addTest("csstransforms",function(){return-1===navigator.userAgent.indexOf("Android 2.")&&y("transform","scale(1)",!0)}),o(),s(g),delete w.addTest,delete w.addAsyncTest;for(var N=0;N<Modernizr._q.length;N++)Modernizr._q\[N]();e.Modernizr=Modernizr}(window,document);

    // Scrollspy
    var createScrollSpy = (function() {

        function targetId(element) {
            return (element.href || "").split("#")[1] || null;
        }

        function getScrollTop() {
            return (window.pageYOffset !== undefined)
                ? window.pageYOffset
                : (document.documentElement || document.body.parentNode || document.body).scrollTop;
        }

        function addClassToParents(element, className, parentClassName) {
            do {
                element = element.parentNode;
            } while (element && element.tagName != "LI")
            if (element) {
                var a = element.querySelector("a");
                if (a) a.className = className;
                addClassToParents(element, parentClassName ? parentClassName : className);
            }
        }

        function getPosition(element, container) {
            var eR = element.getBoundingClientRect();
            var cR = container.getBoundingClientRect();
            if (eR.bottom < cR.top) return "above";
            if (eR.top > cR.bottom) return "below";
            return "visible";
        }

        function createScrollSpy(options) {
            options = options || {};

            var OFFSET = 80,
                needsUpdate = false,
                previous = null,
                current = null,
                currentNav = null,
                tocContainer,
                toc,
                sections;

            tocContainer = document.querySelector(options.id);
            toc = [].slice.call(tocContainer.querySelectorAll("a"), 0);
            sections = toc.reduce(function(sections, a) {
                var id = targetId(a);
                var section = id ? document.getElementById(id) : null;
                if (section) { sections.push(section); }
                return sections;
            }, []);

            function onscroll() {
                if (!needsUpdate) {
                    needsUpdate = true;
                    requestAnimationFrame(updatePosition);
                }
            }

            function updatePosition() {
                needsUpdate = false;
                var scrollTop = (options.offset || 0) + getScrollTop();
                current = sections.filter(function(section){
                    return section.offsetTop < scrollTop;
                }).pop();
                current = current ? current.id : null;

                if (previous !== current) {
                    previous = current;
                    toc.forEach(function(a) {
                        if (targetId(a) == current) {
                            currentNav = a;
                        } else {
                            a.className = "";
                        }
                    });
                    if (options.markParents) {
                        addClassToParents(currentNav, options.className, options.parentClassName)
                    } else {
                        currentNav.className = options.className;
                    }
                    if (options.scrollIntoView && typeof currentNav.scrollIntoView == "function") {
                        var p = getPosition(currentNav, tocContainer);
                        if (p == "above") {
                            currentNav.scrollIntoView(true);
                        } else if (p == "below") {
                            currentNav.scrollIntoView(false);
                        }
                    }
                }
            }

            return {
                start: function() {
                    window.addEventListener("scroll", onscroll, false);
                },

                stop: function() {
                    window.removeEventListener("scroll", onscroll, false);
                    toc.forEach(function(a) {
                        a.className = "";
                    });
                }
            }
        }

        return createScrollSpy;
    })();

    (function() {
        var spy = createScrollSpy({
            offset: 80,
            id: "#toc",
            className: "current",
            parentClassName: "current-parent",
            markParents: true,
            scrollIntoView: true
        });

        var mm = window.matchMedia('screen and (min-width: 78em)');
        if (mm.matches) {
            spy.start();
        }
        mm.addListener(function(m) {
            if (m.matches) spy.start();
            else spy.stop();
        });
    })();
</script>
